Accounts

List, create, change, cancel and delete accounts, with their contacts, addresses, payment methods, notes and related records.

Accounts are the customers and suppliers you bill and buy from. Here you create, read, change, cancel and delete accounts, manage their contacts, addresses, payment methods, billing preferences, notes, image and emails, and list the orders, invoices, payments and other records that belong to an account. This area has 65 endpoints, and every SDK supports all of them.

Purging an account removes it and its records permanently, and cannot be undone.

At a glance

Endpoint	Method	Path	What it does
List accounts	GET	/accounts	Lists your accounts a page at a time, with optional filters and sorting.
Retrieve an account	GET	/accounts/{account_id}	Returns one account with its contacts, addresses, payment methods and billing preferences.
Retrieve an account’s information	GET	/accounts/{account_id}/information	Returns the account under account, the same body as Retrieve an account.
Retrieve an account’s image	GET	/accounts/{account_id}/image	Returns a link to the account’s image, not the image itself.
List an account’s contacts	GET	/accounts/{account_id}/contacts	Returns the account with its contacts under contacts.
Retrieve a contact by slot	GET	/accounts/{account_id}/contacts/{contact_type}	Returns one of the account’s contacts, chosen by its slot.
List an account’s addresses	GET	/accounts/{account_id}/addresses	Returns the account with its addresses under addresses.
Retrieve an address	GET	/accounts/{account_id}/addresses/{address_id}	Returns one of the account’s addresses, by its addr_ id.
Retrieve an account’s billing preferences	GET	/accounts/{account_id}/billing_preferences	Returns the account with its billing_preferences.
List an account’s payment methods	GET	/accounts/{account_id}/payment_methods	Returns the account with its payment methods under payment_methods.
Retrieve a payment method	GET	/accounts/{account_id}/payment_methods/{payment_method_id}	Returns one of the account’s payment methods, under account.payment_method.
List an account’s notes	GET	/accounts/{account_id}/notes	Lists the notes on an account, a page at a time.
Retrieve a note	GET	/accounts/{account_id}/notes/{note_id}	Returns one note on an account, under note.
List an account note’s files	GET	/accounts/{account_id}/notes/{note_id}/files	Lists the files attached to one note.
Retrieve an account note file	GET	/accounts/{account_id}/notes/{note_id}/files/{file_id}	Returns a description of one attached file, under file.
List an account’s emails	GET	/accounts/{account_id}/communications/emails	Lists the emails sent to or from an account, a page at a time.
Retrieve an email	GET	/accounts/{account_id}/communications/emails/{email_id}	Returns one email on an account, under email.
List an account’s orders	GET	/accounts/{account_id}/orders	Lists the orders that belong to one account, a page at a time.
List an account’s invoices	GET	/accounts/{account_id}/invoices	Lists the invoices that belong to one account, a page at a time.
List an account’s payments	GET	/accounts/{account_id}/payments	Lists the payments that belong to one account, a page at a time.
List an account’s refunds	GET	/accounts/{account_id}/refunds	Lists the refunds that belong to one account, a page at a time.
List an account’s credit notes	GET	/accounts/{account_id}/credit_notes	Lists the credit notes that belong to one account, a page at a time.
List an account’s purchase orders	GET	/accounts/{account_id}/purchase_orders	Lists the purchase orders that belong to one account, a page at a time.
List an account’s purchase invoices	GET	/accounts/{account_id}/purchase_invoices	Lists the purchase invoices that belong to one account, a page at a time.
List an account’s purchase payments	GET	/accounts/{account_id}/purchase_payments	Lists the purchase payments that belong to one account, a page at a time.
List an account’s purchase refunds	GET	/accounts/{account_id}/purchase_refunds	Lists the purchase refunds that belong to one account, a page at a time.
List custom objects for accounts	GET	/accounts/{account_id}/custom_objects	Lists the custom objects defined for accounts, a page at a time.
List an account’s inventories	GET	/accounts/{account_id}/inventories	Returns the account with its inventories under account.inventories.
List an account’s partial invoices from quotes	GET	/accounts/{account_id}/quote_partial_invoices	Returns the account with its partial invoices under account.partial_invoices.
Create an account	POST	/accounts	Creates an account and returns it under account.
Replace an account	PUT	/accounts/{account_id}	Rewrites an account’s fields and returns the account.
Cancel an account	POST	/accounts/{account_id}/cancel	Cancels an account from a date and returns it.
Reactivate an account	POST	/accounts/{account_id}/reactivate	Reactivates a cancelled account and returns it.
Set an account’s portal password	POST	/accounts/{account_id}/set-password	Sets the password the account uses to sign in to the portal.
Update an account’s information	PATCH	/accounts/{account_id}/information	Changes an account’s core fields and returns the account.
Add contacts to an account	POST	/accounts/{account_id}/contacts	Adds one or more contacts to an account and returns the account.
Add addresses to an account	POST	/accounts/{account_id}/addresses	Adds one or more addresses to an account and returns the account.
Update an address	PATCH	/accounts/{account_id}/addresses/{address_id}	Changes some fields of one address and returns the account.
Replace an address	PUT	/accounts/{account_id}/addresses/{address_id}	Rewrites one address and returns the account.
Update a contact	PATCH	/accounts/{account_id}/contacts/{contact_id}	Changes some fields of one contact and returns the account.
Replace a contact	PUT	/accounts/{account_id}/contacts/{contact_id}	Rewrites one contact and returns the account.
Replace an account’s billing preferences	PUT	/accounts/{account_id}/billing_preferences	Sets an account’s billing preferences and returns the account.
Add a payment method	POST	/accounts/{account_id}/payment_methods	Adds one payment method to an account and returns the account.
Update a payment method	PATCH	/accounts/{account_id}/payment_methods/{payment_method_id}	Changes some fields of one payment method and returns the account.
Replace a payment method	PUT	/accounts/{account_id}/payment_methods/{payment_method_id}	Rewrites one payment method and returns the account.
Create a note	POST	/accounts/{account_id}/notes	Adds a note to an account, with optional file attachments, and returns it.
Update a note	PATCH	/accounts/{account_id}/notes/{note_id}	Changes a note’s text and returns it.
Upload an account’s image	POST	/accounts/{account_id}/image	Sets the account’s image from base64 data and returns the account.
Create a custom object instance	POST	/accounts/{account_id}/custom_objects/{custom_object_id}	Creates an instance of a custom object on an account.
Update a custom object instance	PATCH	/accounts/{account_id}/custom_objects_instances/{custom_object_instance_id}	Changes an instance’s values and returns the account.
Send and log an email	POST	/accounts/{account_id}/communications/emails	Sends an email and records it on the account.
Purge an account	POST	/accounts/{account_id}/purge	Permanently removes an account and its records.
Delete an account	DELETE	/accounts/{account_id}	Deletes an account.
Delete a contact	DELETE	/accounts/{account_id}/contacts/{contact_id}	Removes one contact from an account.
Delete an address	DELETE	/accounts/{account_id}/addresses/{address_id}	Removes one address from an account.
Delete a payment method	DELETE	/accounts/{account_id}/payment_methods/{payment_method_id}	Removes one payment method from an account.
Delete a note	DELETE	/accounts/{account_id}/notes/{note_id}	Removes one note from an account.
Delete an account’s image	DELETE	/accounts/{account_id}/image	Removes the account’s image.
Retrieve an account’s KPIs	GET	/accounts/{account_id}/kpis	Returns the account’s revenue and order counters, under account_kpis.
Retrieve an account’s financial summary	GET	/accounts/{account_id}/financial_summary	Returns the account’s invoice totals, under account.financial_summary.
Retrieve a custom object with its instances	GET	/accounts/{account_id}/custom_objects/{custom_object_id}	Returns one custom object with this account’s instances of it, under custom_object.
Retrieve a custom object instance	GET	/accounts/{account_id}/custom_objects/{custom_object_id}/instances/{custom_object_instance_id}	Returns one custom object instance on an account, under custom_object_instance.
List an account’s component objects	GET	/accounts/{account_id}/component/{component_id}	Lists one component’s objects under an account and its child accounts, a page at a time.
Retrieve an account’s component object	GET	/accounts/{account_id}/component/{component_id}/{component_object_id}	Returns one component object under an account, under custom_component_object.
Delete an account note file	DELETE	/accounts/{account_id}/notes/{note_id}/files/{file_id}	Removes one attachment from a note.

Before you call

Register your API credentials once when your app starts, as shown in Authentication. Every SDK sample on these pages then gets its client in one line. With cURL, send the access token in an Authorization header: Authorization: Bearer $ACCESS_TOKEN.

Things to know

• Paths take the account’s id, not its uuid. The id is a short code such as ACC0001; passing the uuid returns 404.
• Most writes wrap their fields in one key. Account writes use account, a single address address, a contact contact, a payment method payment_method and billing preferences billing_preferences. Adding contacts takes a top-level contacts list and adding addresses a top-level addresses list. Setting a password, sending an email and uploading an image take their fields at the top level. Custom object instance writes use custom_object_instances, and notes are sent as a multipart form.
• Contacts and payment methods are read by one value and written by another. Retrieve a contact with its slot, CONTACT_1 to CONTACT_5, and update, replace or delete it with its con_ id; a contact created as CONTACT_1 reads back with type billing. Retrieve a payment method with its reference, and update, replace or delete it with its id, as listed under payment_methods.
• Writes are flatter than reads. currency and time_zone go in as a code and a name and read back as objects, an address is written with post_code and reads back with postal_code, and a contact’s name is written as first_name and last_name and reads back under name.
• Many reads and most writes return the whole account under account. Note writes return the note, sending an email returns the email, and deletes return 204 with no body. The contacts, addresses, payment methods, billing preferences, inventories and partial invoice reads return the account, carrying the part asked for, rather than a paged listing.
• Paged listings use a cursor. Records come under data with a pagination object; while has_more is true, pass pagination.next_cursor as cursor to get the next page.