Companies

Companies are accessible under the https://*.recras.nl/api2/bedrijven (companies) namespace.

Create

POST /api2/bedrijven

Create a company

Example request

POST /api2/bedrijven HTTP/1.1
Host: demo.recras.nl
Accept: application/json

{
    "bedrijfsnaam": "Company name (internal)",
    "weergavenaam": "Company name (as communicated to customers)",
    "slogan": "Company's slogan",
    "email": "company@example.com",
    "factuur_pdf_template_id": 3,

    "onderwerp_mail_eindfactuur": "Final invoice email subject",
    "body_mail_eindfactuur": "Final invoice email body",

    "onderwerp_eerste_betalingsherinnering": "First payment reminder email subject",
    "body_eerste_betalingsherinnering": "First payment reminder email body",

    "onderwerp_tweede_betalingsherinnering": "Second payment reminder email subject",
    "body_tweede_betalingsherinnering": "Second payment reminder email body",

    "onderwerp_betaalbevestiging": "Payment confirmation email subject",
    "body_betaalbevestiging": "Payment confirmation email body",

    "factuur_betaaltermijn": 30
}
Status Codes:

  • 201 Created – Resource created

  • 403 Forbidden – Authenticated user lacks the editBedrijfsgegevens (editCompanyDetails) permission.

Response Headers:

  • Location – The URI of the newly created resource.

JSON Parameters:

  • bedrijfsnaam (string) – The internal company name (bedrijfsnaam means company_name)

  • weergavenaam (string) – The company name as communicated to customers. Will take the value of bedrijfsnaam (company_name) if empty. (weergavenaam means display_name)

  • slogan (string) – The company slogan

  • email (email) – Required. The envelope address for emails sent from this company

  • factuur_betaaltermijn (integer) – The default number of days to set the payment deadline for invoices. Must be ≥ 0, see v1.0.1 (2020-06) (factuur_betaaltermijn means invoice_payment_term)

  • factuur_pdf_template_id (integer) – Required. The ID of a PDF template with the invoice context. (factuur_pdf_template_id means invoice_pdf_template_id)

  • onderwerp_mail_eindfactuur (string) – Required. The default subject line for invoice emails. (onderwerp_mail_eindfactuur means subject_email_final_invoice)

  • body_mail_eindfactuur (string) – Required. The default body for invoice emails. (body_mail_eindfactuur means body_email_final_invoice)

  • onderwerp_eerste_betalingsherinnering (string) – Required. The subject line for the first invoice reminder. (onderwerp_eerste_betalingsherinnering means subject_first_payment_reminder)

  • body_eerste_betalingsherinnering (string) – Required. The body for the first invoice reminder. (body_eerste_betalingsherinnering means body_first_payment_reminder)

  • onderwerp_tweede_betalingsherinnering (string) – Required. The subject line for the second invoice reminder. (onderwerp_tweede_betalingsherinnering means subject_second_payment_reminder)

  • body_tweede_betalingsherinnering (string) – Required. The body for the second invoice reminder. (body_tweede_betalingsherinnering means body_second_payment_reminder)

  • onderwerp_betaalbevestiging (string) – Required. The subject line for the payment confirmation. (onderwerp_betaalbevestiging means subject_payment_confirmation)

  • body_betaalbevestiging (string) – Required. The body for the payment confirmation. (body_betaalbevestiging means body_payment_confirmation)

  • other_fields (mixed) – This documentation is incomplete, please contact the Recras development team if you have specific questions regarding this API.

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": 8,
    "bedrijfsnaam": "Company name (internal)", // (company_name)
    "weergavenaam": "Company name (as communicated to customers)", // (display_name)
    "slogan": "Company's slogan",
    "adres": null, // (address)
    "postcode": null, // (postal_code)
    "plaats": null, // (city)
    "landcode": null, // (country_code)
    "iban": null,
    "bic": null,
    "bank_tnv": null, // (bank_account_holder)
    "btw_nummer": null, // (vat_number)
    "kvk_nummer": null, // (chamber_of_commerce_number)
    "factuur_betaaltermijn": 30, // (invoice_payment_term)
    "website": null,
    "telefoon": null, // (phone)
    "soort_klanten": [], // (customer_types)
    "free_relation_fields": [],
    "email": "company@example.com",
    "smtp_integration_id": null,
    "ondertekening_standaardmails": null, // (signature_standard_emails)
    "programmarender_aantallen": false, // (program_render_quantities)
    "default_font": "Arial",
    "factureren_na_dagen": 0, // (invoice_after_days)
    "factuur_pdf_template_id": 3, // (invoice_pdf_template_id)
    "kassa_factuur_pdf_template_id": null, // (pos_invoice_pdf_template_id)
    "online_boeking_factuur_pdf_template_id": null, // (online_booking_invoice_pdf_template_id)
    "onderwerp_mail_eindfactuur": "Final invoice email subject", // (subject_email_final_invoice)
    "body_mail_eindfactuur": "Final invoice email body", // (body_email_final_invoice)
    "onderwerp_eerste_betalingsherinnering": "First payment reminder email subject", // (subject_first_payment_reminder)
    "body_eerste_betalingsherinnering": "First payment reminder email body", // (body_first_payment_reminder)
    "onderwerp_tweede_betalingsherinnering": "Second payment reminder email subject", // (subject_second_payment_reminder)
    "body_tweede_betalingsherinnering": "Second payment reminder email body", // (body_second_payment_reminder)
    "onderwerp_betaalbevestiging": "Payment confirmation email subject", // (subject_payment_confirmation)
    "body_betaalbevestiging": "Payment confirmation email body", // (body_payment_confirmation)
    "locale": "nl_NL",
    "standaard_aanhef": "Beste {contactpersoon_aanspreeknaam}", // (default_salutation: "Dear {contact_person_salutation_name}")
    "attentietekst": "t.a.v.", // (attention_text: "attn.")
    "standaard_titel_man": "meneer", // (default_title_male: "mr")
    "standaard_titel_vrouw": "mevrouw", // (default_title_female: "mrs/ms")
    "latitude": null,
    "longitude": null,
    "communication_default_mail_subject": "",
    "mollie_api_key": "",
    "deleted_at": null,
    "logo_href": null,
    "is_deletable": true,
    "_links": {
        "meta": {
            "delete_reasons": []
        }
    }
}

Read

GET /api2/bedrijven

Retrieve a list of companies

Query Parameters:

  • is_deleted (boolean) – Default: empty. With a true value, previously deleted companies will be included in the result.

Status Codes:
GET /api2/bedrijven/(int: id)

Retrieve a single company resource.

Status Codes:
JSON Parameters:

Update

PUT /api2/bedrijven/(int: id)

The companies-endpoint supports PUT-back semantics: please retrieve a resource, update some values and send everything back. Partial updates may work but are not supported.

Status Codes:

  • 200 OK – OK

  • 403 Forbidden – Authenticated user lacks the editBedrijfsgegevens (editCompanyDetails) permission

  • 406 Not Acceptable – Error in the payload, expect the response to be a list of error objects.

Delete

DELETE /api2/bedrijven/(int: id)

This resource has soft-delete semantics: deleting it does not remove it from the database, but archives it and makes it invisible. This endpoint is only available for resources with the is_deletable flag set to true. See GET /api2/bedrijven/(int:id).

Status Codes:

Version history

v1.0.1 (2020-06)

Fixed factuur_betaaltermijn (invoice_payment_term), which used to accept negative values. This would trigger errors in calculating the payment deadline of invoices, thus failing to render the invoice.

v1.0.0

Original version, released way in the past.