Contacts
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
Required scope(s)
contacts
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_emaildirect_debitsepa_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 | |
| - | - | - | - |
Required scope(s)
contacts
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
filterComma-separated key:value terms (e.g. first_name:henk,contact_type:company). See the operation description for available keys.
queryFree-text search across name, contact people, email, phone, customer id, tax number, chamber of commerce, IBAN, and address fields.
include_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_emaildirect_debitsepa_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.
Required scope(s)
contacts
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
filterComma-separated key:value filter terms. Same syntax as GET /contacts/filter — see that operation's description for the available keys.
include_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.
Required scope(s)
contacts
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_emaildirect_debitsepa_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.
Required scope(s)
contacts
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.
Required scope(s)
contacts
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.
Required scope(s)
contacts
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.
Required scope(s)
contacts
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.
Required scope(s)
sales_invoices and settings
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.
Required scope(s)
sales_invoices and settings
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.
Required scope(s)
contacts
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.
Required scope(s)
contacts
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.
Required scope(s)
contacts
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.
Required scope(s)
sales_invoices
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.
Required scope(s)
sales_invoices
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.
Required scope(s)
contacts
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.
Required scope(s)
contacts
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_emaildirect_debitsepa_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.
Required scope(s)
contacts
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.
Required scope(s)
contacts
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_emaildirect_debitsepa_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
Required scope(s)
contacts
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_valuecontact_import_idRestrict to contacts created by the given contact import batch.
List 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_emaildirect_debitsepa_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.
Required scope(s)
contacts
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_emaildirect_debitsepa_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