Contacts are the entities in Moneybird that represent your customers, suppliers or other business relations. Use the following endpoints to get information about contacts, create new contacts or update existing contacts.
Get contact by customer id
Returns all information about a contact by the given customer id
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
customer_id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Get contact by customer id › Responses
A contact
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
company_namefirstnamelastnameaddress1address2zipcodecitycountryphonedelivery_methodcustomer_idWill be assigned automatically if empty
tax_numberchamber_of_commercebank_accountThe SEPA IBAN of the contact, can be empty if no SEPA IBAN is set
is_trustedmax_transfer_amountattentionemailemail_ublsend_invoices_to_attentionsend_invoices_to_emailsend_estimates_to_attentionsend_estimates_to_emailsepa_activesepa_ibansepa_iban_account_namesepa_bicsepa_mandate_idsepa_mandate_datesepa_sequence_typecredit_card_numbercredit_card_referencecredit_card_typetax_number_validated_attax_number_validinvoice_workflow_id^\d+$A unique record identifier
estimate_workflow_id^\d+$A unique record identifier
si_identifiersi_identifier_typemoneybird_payments_mandateWhether the contact has a valid Moneybird Payments mandate
created_atupdated_atversionsales_invoices_url^https:\/\/moneybird…archivedFilter contacts
Returns a paginated list of all contacts in the administration.
The filter argument allows you to filter the list of contacts. Filters are a combination of keys and values,
separated by a comma: first_name:henk,last_name:jansen. The available options for filtering are:
| Filter | Type | Default | Description |
|---|---|---|---|
| created_after | String | Select contacts created after the given time (exclusive). ISO 8601 formatted string. The time to compare with is in UTC timezone | |
| updated_after | String | Select contacts updated after the given time (exclusive). ISO 8601 formatted string. The time to compare with is in UTC timezone | |
| first_name | String | Select contacts with the given first name. Case-insensitive | |
| last_name | String | Select contacts with the given last name. Case-insensitive | |
| estimate_workflow_id | Integer | Filters contacts by a single Estimate workflow | |
| invoice_workflow_id | Integer | Filters contacts by a single Invoice workflow | |
| contact_type | String | The contact type. Possible values all, company, private_individual | |
| delivery_method | String | The delivery method for invoices. Possible values. Possible values all, email, post, manual, peppol, simplerinvoicing | |
| trusted_type | String | Whether the contact is trusted. Possible values all, trusted, not_trusted | |
| - | - | - | - |
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
query Parameters
filterinclude_archivedpageper_page^\d+$Filter contacts › Responses
A list of contacts
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
company_namefirstnamelastnameaddress1address2zipcodecitycountryphonedelivery_methodcustomer_idWill be assigned automatically if empty
tax_numberchamber_of_commercebank_accountThe SEPA IBAN of the contact, can be empty if no SEPA IBAN is set
is_trustedmax_transfer_amountattentionemailemail_ublsend_invoices_to_attentionsend_invoices_to_emailsend_estimates_to_attentionsend_estimates_to_emailsepa_activesepa_ibansepa_iban_account_namesepa_bicsepa_mandate_idsepa_mandate_datesepa_sequence_typecredit_card_numbercredit_card_referencecredit_card_typetax_number_validated_attax_number_validinvoice_workflow_id^\d+$A unique record identifier
estimate_workflow_id^\d+$A unique record identifier
si_identifiersi_identifier_typemoneybird_payments_mandateWhether the contact has a valid Moneybird Payments mandate
created_atupdated_atversionsales_invoices_url^https:\/\/moneybird…archivedList all ids and versions
Returns all contacts in the administration. The list contains the contact id and the version of the contact.
Check if the version of the contact is newer than the version you have stored locally, use the POST
variant for fetching contacts with the given ids.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
query Parameters
filterinclude_archivedList all ids and versions › Responses
IDs and versions of records
idversionFetch contacts with given ids
Given a list of contact ids, returns the contact information belonging to the contacts. Returns a maximum of 100 contacts, even if more ids are provided.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Fetch contacts with given ids › Responses
A list of contacts
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
company_namefirstnamelastnameaddress1address2zipcodecitycountryphonedelivery_methodcustomer_idWill be assigned automatically if empty
tax_numberchamber_of_commercebank_accountThe SEPA IBAN of the contact, can be empty if no SEPA IBAN is set
is_trustedmax_transfer_amountattentionemailemail_ublsend_invoices_to_attentionsend_invoices_to_emailsend_estimates_to_attentionsend_estimates_to_emailsepa_activesepa_ibansepa_iban_account_namesepa_bicsepa_mandate_idsepa_mandate_datesepa_sequence_typecredit_card_numbercredit_card_referencecredit_card_typetax_number_validated_attax_number_validinvoice_workflow_id^\d+$A unique record identifier
estimate_workflow_id^\d+$A unique record identifier
si_identifiersi_identifier_typemoneybird_payments_mandateWhether the contact has a valid Moneybird Payments mandate
created_atupdated_atversionsales_invoices_url^https:\/\/moneybird…archivedGet contact person
Returns all information about a contact person.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
contact_id^\d+$ · requiredA unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Get contact person › Responses
A contact person
id^\d+$A unique record identifier
contact_id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
firstnamelastnamephoneemaildepartmentcreated_atupdated_atversionDelete a contact person
Deletes a contact person.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
contact_id^\d+$ · requiredA unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Delete a contact person › Responses
Contact person deleted
Update a contact person
When updating a contact, you only need to provide the information you want to change. Attributes you don't provide in the request will not be updated.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
contact_id^\d+$ · requiredA unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Update a contact person › Responses
Contact person updated
id^\d+$A unique record identifier
contact_id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
firstnamelastnamephoneemaildepartmentcreated_atupdated_atversionCreate a new contact person
Creating a new contact person in the administration requires at least a contact_person hash including firstname and lastname.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
contact_id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Create a new contact person › Responses
Contact person created
id^\d+$A unique record identifier
contact_id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
firstnamelastnamephoneemaildepartmentcreated_atupdated_atversionRequest an URL for setting up a Moneybird Payments mandate
Obtains an URL for setting up a Moneybird Payments mandate. You must provide this URL to your contact to set-up the mandate. Your contact is required to make a 15 cent payment. Every generated URL using this endpoint is valid for 14 days after creation. Only available when Moneybird Payments is enabled for the administration.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
contact_id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Request an URL for setting up a Moneybird Payments mandate › Responses
A URL for setting up a Moneybird Payments mandate
urlGet Moneybird Payments mandate
Returns information about the stored Moneybird Payments mandate. Only available when Moneybird Payments is enabled for the administration.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
contact_id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Get Moneybird Payments mandate › Responses
A Moneybird Payments mandate
typesepa_mandatebankibanbiciban_account_namecard_expiry_monthcard_expiry_yearcard_final_digitscreated_atRequest a new Moneybird Payments mandate
Sends a request for a Moneybird Payments mandate to a contact via e-mail. Your contact will receive an email containing a link to authorise direct debit payments through Moneybird Payments. Your contact is required to make a 15 cent payment. Only available when Moneybird Payments is enabled for the administration.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
contact_id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Request a new Moneybird Payments mandate › Responses
Moneybird Payments mandate requested
Delete a stored Moneybird Payments mandate
Deletes the stored Moneybird Payments mandate for the contact. Only available when Moneybird Payments is enabled for the administration.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
contact_id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Delete a stored Moneybird Payments mandate › Responses
Contact deleted
Destroys note from entity
Deletes a note from the contact.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
contact_id^\d+$ · requiredA unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Destroys note from entity › Responses
Note deleted
Adds note to entity
Adds a note to the contact.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
contact_id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Adds note to entity › Responses
Note created
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
entity_id^\d+$A unique record identifier
entity_typeuser_id^\d+$A unique record identifier
assignee_id^\d+$A unique record identifier
todonotecompleted_atcompleted_by_id^\d+$A unique record identifier
todo_typedatacreated_atupdated_atGet additional charges
Get the additional charges of the given contact.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
query Parameters
include_billedIf true, includes the additional charges that have already been billed. Default is false.
Get additional charges › Responses
A list of additional charges
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
contact_id^\d+$A unique record identifier
subscription_id^\d+$A unique record identifier
product_id^\d+$A unique record identifier
detail_id^\d+$A unique record identifier
amountpriceperiod^[0-9]{6}..[0-9]{6}$descriptionCreate an additional charge to be invoiced at start of next period
At the end of the current period, the additional charges for a contact are merged where possible and an invoice will be created for them. The invoice will be scheduled for sending at the first day of the next month.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Create an additional charge to be invoiced at start of next period › Responses
Subscription additional charge created
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
contact_id^\d+$A unique record identifier
subscription_id^\d+$A unique record identifier
product_id^\d+$A unique record identifier
detail_id^\d+$A unique record identifier
amountpriceperiod^[0-9]{6}..[0-9]{6}$descriptionArchive a contact
Archives a contact.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Archive a contact › Responses
Contact archived
Get contact
Returns all information about a contact.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
query Parameters
include_archivedGet contact › Responses
A contact
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
company_namefirstnamelastnameaddress1address2zipcodecitycountryphonedelivery_methodcustomer_idWill be assigned automatically if empty
tax_numberchamber_of_commercebank_accountThe SEPA IBAN of the contact, can be empty if no SEPA IBAN is set
is_trustedmax_transfer_amountattentionemailemail_ublsend_invoices_to_attentionsend_invoices_to_emailsend_estimates_to_attentionsend_estimates_to_emailsepa_activesepa_ibansepa_iban_account_namesepa_bicsepa_mandate_idsepa_mandate_datesepa_sequence_typecredit_card_numbercredit_card_referencecredit_card_typetax_number_validated_attax_number_validinvoice_workflow_id^\d+$A unique record identifier
estimate_workflow_id^\d+$A unique record identifier
si_identifiersi_identifier_typemoneybird_payments_mandateWhether the contact has a valid Moneybird Payments mandate
created_atupdated_atversionsales_invoices_url^https:\/\/moneybird…archivedDelete a contact
Deletes a contact.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Delete a contact › Responses
Contact deleted
Update a contact
When updating a contact, you only need to provide the information you want to change. Attributes you don't provide in the request will not be updated. Optional attributes can be removed by setting them to an empty string value.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Update a contact › Responses
Contact updated
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
company_namefirstnamelastnameaddress1address2zipcodecitycountryphonedelivery_methodcustomer_idWill be assigned automatically if empty
tax_numberchamber_of_commercebank_accountThe SEPA IBAN of the contact, can be empty if no SEPA IBAN is set
is_trustedmax_transfer_amountattentionemailemail_ublsend_invoices_to_attentionsend_invoices_to_emailsend_estimates_to_attentionsend_estimates_to_emailsepa_activesepa_ibansepa_iban_account_namesepa_bicsepa_mandate_idsepa_mandate_datesepa_sequence_typecredit_card_numbercredit_card_referencecredit_card_typetax_number_validated_attax_number_validinvoice_workflow_id^\d+$A unique record identifier
estimate_workflow_id^\d+$A unique record identifier
si_identifiersi_identifier_typemoneybird_payments_mandateWhether the contact has a valid Moneybird Payments mandate
created_atupdated_atversionsales_invoices_url^https:\/\/moneybird…archivedList all contacts
Returns a paginated list of contacts in the administration.
Searching for contacts can be done by providing the query parameter with search terms. The API searches for matches in the following contact fields:
company_nameattentionfirstnamelastnameaddress1address2zipcodecitycountryemailphonecustomer_idtax_numberchamber_of_commercebank_account
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
query Parameters
per_page^\d+$pagequeryinclude_archivedtodocontact_fieldcontact_valueList all contacts › Responses
A list of contacts
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
company_namefirstnamelastnameaddress1address2zipcodecitycountryphonedelivery_methodcustomer_idWill be assigned automatically if empty
tax_numberchamber_of_commercebank_accountThe SEPA IBAN of the contact, can be empty if no SEPA IBAN is set
is_trustedmax_transfer_amountattentionemailemail_ublsend_invoices_to_attentionsend_invoices_to_emailsend_estimates_to_attentionsend_estimates_to_emailsepa_activesepa_ibansepa_iban_account_namesepa_bicsepa_mandate_idsepa_mandate_datesepa_sequence_typecredit_card_numbercredit_card_referencecredit_card_typetax_number_validated_attax_number_validinvoice_workflow_id^\d+$A unique record identifier
estimate_workflow_id^\d+$A unique record identifier
si_identifiersi_identifier_typemoneybird_payments_mandateWhether the contact has a valid Moneybird Payments mandate
created_atupdated_atversionsales_invoices_url^https:\/\/moneybird…archivedCreate a new contact
Creating a new contact in the administration requires at least a company_name or a firstname and lastname.
When filling a custom field, both id and value are required. See the custom field example for more information.
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Create a new contact › Responses
Contact created
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
company_namefirstnamelastnameaddress1address2zipcodecitycountryphonedelivery_methodcustomer_idWill be assigned automatically if empty
tax_numberchamber_of_commercebank_accountThe SEPA IBAN of the contact, can be empty if no SEPA IBAN is set
is_trustedmax_transfer_amountattentionemailemail_ublsend_invoices_to_attentionsend_invoices_to_emailsend_estimates_to_attentionsend_estimates_to_emailsepa_activesepa_ibansepa_iban_account_namesepa_bicsepa_mandate_idsepa_mandate_datesepa_sequence_typecredit_card_numbercredit_card_referencecredit_card_typetax_number_validated_attax_number_validinvoice_workflow_id^\d+$A unique record identifier
estimate_workflow_id^\d+$A unique record identifier
si_identifiersi_identifier_typemoneybird_payments_mandateWhether the contact has a valid Moneybird Payments mandate
created_atupdated_atversionsales_invoices_url^https:\/\/moneybird…archived