All API resources
Contacts
Customers and suppliers: create, update, archive, restore and delete them.
Base URL https://app.prosaic.works/api/public/v1. Every request needs an API key or access token; see the overview.
List contacts
/api/public/v1/contactsSDK: prosaic.contacts.list(params)
Returns non-deleted contacts from entities visible in the active workspace.
Query parameters
entityIdstringtypestringOne of:
BUSINESS,INDIVIDUALstatusstringOne of:
active,archived,allupdatedSincestringpageintegerDefault:
1pageSizeintegerDefault:
100
Responses
200 Successful response
dataarray of objectsrequiredpaginationobjectrequiredShow 6 child attributesHide child attributes
currentPagenumberrequiredpageSizenumberrequiredtotalCountnumberrequiredtotalPagesnumberrequiredhasNextPagebooleanrequiredhasPreviousPagebooleanrequired
400Invalid query parameters.401Unauthorized.403Insufficient role or token scope.500Internal server error.
const page = await prosaic.contacts.list();curl https://app.prosaic.works/api/public/v1/contacts \
-H "Authorization: Bearer $PROSAIC_API_KEY"Get a contact
/api/public/v1/entities/{entityId}/contacts/{contactId}SDK: prosaic.contacts.retrieve(entityId, contactId)
Returns one active or archived contact belonging to the path entity.
Path parameters
entityIdstringrequiredcontactIdstringrequired
Responses
200 Successful response
dataobjectrequiredOne of: type: BUSINESS
typestringrequiredOne of:
BUSINESSpeoplearray of objectsrequiredShow 6 child attributesHide child attributes
idstringrequireddisplayNamestringrequiredreceivesInvoicesbooleanrequiredstatusstringrequiredOne of:
active,archivedarchivedAtstring (date-time)requirednullableemailsarray of objectsrequiredShow 3 child attributesHide child attributes
idstringrequiredemailstringrequiredlabelstringrequirednullable
idstringrequiredworkspaceIdstringrequiredentityIdstringrequiredstatusstringrequiredOne of:
active,archiveddisplayNamestringrequiredlegalNamestringrequirednullableidentifierSchemestringrequirednullableidentifierstringrequirednullablegstNumberstringrequirednullablewebsitestringrequirednullablenotesstringrequirednullableinvoiceNotesstringrequirednullableorganisationIdstringrequirednullablereceivesInvoicesbooleanrequiredaddressesarray of objectsrequiredShow 12 child attributesHide child attributes
idstringrequiredlabelstringtypestringrequiredOne of:
BILLING,DELIVERY,POSTAL,PHYSICAL,REMITTANCE,OTHERattentionTostringaddressLinesarray of stringsrequiredsublocalitystringlocalitystringadministrativeAreastringpostalCodestringsortingCodestringcountryCodestringrequiredisInvoiceDefaultbooleanrequired
phonesarray of objectsrequiredShow 4 child attributesHide child attributes
idstringrequiredlabelstringnumberstringrequiredisPrimarybooleanrequired
organisationobjectrequirednullableShow 2 child attributesHide child attributes
idstringrequireddisplayNamestringrequired
createdAtstring (date-time)requiredupdatedAtstring (date-time)requiredarchivedAtstring (date-time)requirednullable
One of: type: INDIVIDUAL
typestringrequiredOne of:
INDIVIDUALemailsarray of objectsrequiredShow 3 child attributesHide child attributes
idstringrequiredemailstringrequiredlabelstringrequirednullable
idstringrequiredworkspaceIdstringrequiredentityIdstringrequiredstatusstringrequiredOne of:
active,archiveddisplayNamestringrequiredlegalNamestringrequirednullableidentifierSchemestringrequirednullableidentifierstringrequirednullablegstNumberstringrequirednullablewebsitestringrequirednullablenotesstringrequirednullableinvoiceNotesstringrequirednullableorganisationIdstringrequirednullablereceivesInvoicesbooleanrequiredaddressesarray of objectsrequiredShow 12 child attributesHide child attributes
idstringrequiredlabelstringtypestringrequiredOne of:
BILLING,DELIVERY,POSTAL,PHYSICAL,REMITTANCE,OTHERattentionTostringaddressLinesarray of stringsrequiredsublocalitystringlocalitystringadministrativeAreastringpostalCodestringsortingCodestringcountryCodestringrequiredisInvoiceDefaultbooleanrequired
phonesarray of objectsrequiredShow 4 child attributesHide child attributes
idstringrequiredlabelstringnumberstringrequiredisPrimarybooleanrequired
organisationobjectrequirednullableShow 2 child attributesHide child attributes
idstringrequireddisplayNamestringrequired
createdAtstring (date-time)requiredupdatedAtstring (date-time)requiredarchivedAtstring (date-time)requirednullable
400Invalid contact ID.401Unauthorized.403Insufficient workspace role.404Contact or entity not found.500Internal server error.
const { data } = await prosaic.contacts.retrieve(entityId, contactId);curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts/$CONTACT_ID \
-H "Authorization: Bearer $PROSAIC_API_KEY"Create a contact
/api/public/v1/entities/{entityId}/contactsSDK: prosaic.contacts.create(entityId, params)
Creates a contact in the path entity and returns its public representation.
Path parameters
entityIdstringrequired
Request body
application/json
One of — With displayName, type
displayNamestringrequiredtypestringrequiredOne of:
BUSINESS,INDIVIDUALemailobjectShow 2 child attributesHide child attributes
emailstringrequiredlabelstring
peoplearray of objectsShow 5 child attributesHide child attributes
receivesInvoicesbooleanidstringemailstringlabelstringdisplayNamestring
phonesarray of objectsShow 4 child attributesHide child attributes
idstringrequirednumberstringrequiredlabelstringisPrimaryboolean
addressesarray of objectsShow 12 child attributesHide child attributes
idstringrequiredtypestringrequiredOne of:
BILLING,DELIVERY,POSTAL,PHYSICAL,REMITTANCE,OTHERaddressLinesarray of stringsrequiredcountryCodestringrequiredlabelstringattentionTostringsublocalitystringlocalitystringadministrativeAreastringpostalCodestringsortingCodestringisInvoiceDefaultboolean
linkPastInvoicesbooleanlegalNamestringidentifierSchemestringidentifierstringgstNumberstringwebsitestringnotesstringinvoiceNotesstring
One of — With people
peoplearray of objectsrequiredShow 5 child attributesHide child attributes
receivesInvoicesbooleanidstringemailstringlabelstringdisplayNamestring
Responses
201 Successful response
dataobjectrequiredOne of: type: BUSINESS
typestringrequiredOne of:
BUSINESSpeoplearray of objectsrequiredShow 6 child attributesHide child attributes
idstringrequireddisplayNamestringrequiredreceivesInvoicesbooleanrequiredstatusstringrequiredOne of:
active,archivedarchivedAtstring (date-time)requirednullableemailsarray of objectsrequiredShow 3 child attributesHide child attributes
idstringrequiredemailstringrequiredlabelstringrequirednullable
idstringrequiredworkspaceIdstringrequiredentityIdstringrequiredstatusstringrequiredOne of:
active,archiveddisplayNamestringrequiredlegalNamestringrequirednullableidentifierSchemestringrequirednullableidentifierstringrequirednullablegstNumberstringrequirednullablewebsitestringrequirednullablenotesstringrequirednullableinvoiceNotesstringrequirednullableorganisationIdstringrequirednullablereceivesInvoicesbooleanrequiredaddressesarray of objectsrequiredShow 12 child attributesHide child attributes
idstringrequiredlabelstringtypestringrequiredOne of:
BILLING,DELIVERY,POSTAL,PHYSICAL,REMITTANCE,OTHERattentionTostringaddressLinesarray of stringsrequiredsublocalitystringlocalitystringadministrativeAreastringpostalCodestringsortingCodestringcountryCodestringrequiredisInvoiceDefaultbooleanrequired
phonesarray of objectsrequiredShow 4 child attributesHide child attributes
idstringrequiredlabelstringnumberstringrequiredisPrimarybooleanrequired
organisationobjectrequirednullableShow 2 child attributesHide child attributes
idstringrequireddisplayNamestringrequired
createdAtstring (date-time)requiredupdatedAtstring (date-time)requiredarchivedAtstring (date-time)requirednullable
One of: type: INDIVIDUAL
typestringrequiredOne of:
INDIVIDUALemailsarray of objectsrequiredShow 3 child attributesHide child attributes
idstringrequiredemailstringrequiredlabelstringrequirednullable
idstringrequiredworkspaceIdstringrequiredentityIdstringrequiredstatusstringrequiredOne of:
active,archiveddisplayNamestringrequiredlegalNamestringrequirednullableidentifierSchemestringrequirednullableidentifierstringrequirednullablegstNumberstringrequirednullablewebsitestringrequirednullablenotesstringrequirednullableinvoiceNotesstringrequirednullableorganisationIdstringrequirednullablereceivesInvoicesbooleanrequiredaddressesarray of objectsrequiredShow 12 child attributesHide child attributes
idstringrequiredlabelstringtypestringrequiredOne of:
BILLING,DELIVERY,POSTAL,PHYSICAL,REMITTANCE,OTHERattentionTostringaddressLinesarray of stringsrequiredsublocalitystringlocalitystringadministrativeAreastringpostalCodestringsortingCodestringcountryCodestringrequiredisInvoiceDefaultbooleanrequired
phonesarray of objectsrequiredShow 4 child attributesHide child attributes
idstringrequiredlabelstringnumberstringrequiredisPrimarybooleanrequired
organisationobjectrequirednullableShow 2 child attributesHide child attributes
idstringrequireddisplayNamestringrequired
createdAtstring (date-time)requiredupdatedAtstring (date-time)requiredarchivedAtstring (date-time)requirednullable
linkedInvoiceCountnumberrequired
400Invalid JSON401Unauthorized.403Insufficient workspace role or entity permission.404Entity not found.500Internal server error.
const { data } = await prosaic.contacts.create(entityId, {
displayName: 'Example Ltd',
type: 'BUSINESS',
});curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts \
-H "Authorization: Bearer $PROSAIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"displayName": "Example Ltd",
"type": "BUSINESS"
}'Update a contact
/api/public/v1/entities/{entityId}/contacts/{contactId}SDK: prosaic.contacts.update(entityId, contactId, params)
Updates only the supplied mutable fields on an active contact. Omitted fields, including nested email labels and person invoice preferences, are unchanged; send null to clear an email label. Type and entity cannot be changed.
Path parameters
entityIdstringrequiredcontactIdstringrequired
Request body
application/json
displayNamestringemailobjectnullableShow 2 child attributesHide child attributes
emailstringrequiredlabelstringnullable
peoplearray of objectsShow 5 child attributesHide child attributes
receivesInvoicesbooleanidstringemailstringlabelstringdisplayNamestring
phonesarray of objectsShow 4 child attributesHide child attributes
idstringrequirednumberstringrequiredlabelstringisPrimaryboolean
addressesarray of objectsShow 12 child attributesHide child attributes
idstringrequiredtypestringrequiredOne of:
BILLING,DELIVERY,POSTAL,PHYSICAL,REMITTANCE,OTHERaddressLinesarray of stringsrequiredcountryCodestringrequiredlabelstringattentionTostringsublocalitystringlocalitystringadministrativeAreastringpostalCodestringsortingCodestringisInvoiceDefaultboolean
linkPastInvoicesbooleanlegalNamestringnullableidentifierSchemestringnullableidentifierstringnullablegstNumberstringnullablewebsitestringnullablenotesstringnullableinvoiceNotesstringnullable
Responses
200 Successful response
dataobjectrequiredOne of: type: BUSINESS
typestringrequiredOne of:
BUSINESSpeoplearray of objectsrequiredShow 6 child attributesHide child attributes
idstringrequireddisplayNamestringrequiredreceivesInvoicesbooleanrequiredstatusstringrequiredOne of:
active,archivedarchivedAtstring (date-time)requirednullableemailsarray of objectsrequiredShow 3 child attributesHide child attributes
idstringrequiredemailstringrequiredlabelstringrequirednullable
idstringrequiredworkspaceIdstringrequiredentityIdstringrequiredstatusstringrequiredOne of:
active,archiveddisplayNamestringrequiredlegalNamestringrequirednullableidentifierSchemestringrequirednullableidentifierstringrequirednullablegstNumberstringrequirednullablewebsitestringrequirednullablenotesstringrequirednullableinvoiceNotesstringrequirednullableorganisationIdstringrequirednullablereceivesInvoicesbooleanrequiredaddressesarray of objectsrequiredShow 12 child attributesHide child attributes
idstringrequiredlabelstringtypestringrequiredOne of:
BILLING,DELIVERY,POSTAL,PHYSICAL,REMITTANCE,OTHERattentionTostringaddressLinesarray of stringsrequiredsublocalitystringlocalitystringadministrativeAreastringpostalCodestringsortingCodestringcountryCodestringrequiredisInvoiceDefaultbooleanrequired
phonesarray of objectsrequiredShow 4 child attributesHide child attributes
idstringrequiredlabelstringnumberstringrequiredisPrimarybooleanrequired
organisationobjectrequirednullableShow 2 child attributesHide child attributes
idstringrequireddisplayNamestringrequired
createdAtstring (date-time)requiredupdatedAtstring (date-time)requiredarchivedAtstring (date-time)requirednullable
One of: type: INDIVIDUAL
typestringrequiredOne of:
INDIVIDUALemailsarray of objectsrequiredShow 3 child attributesHide child attributes
idstringrequiredemailstringrequiredlabelstringrequirednullable
idstringrequiredworkspaceIdstringrequiredentityIdstringrequiredstatusstringrequiredOne of:
active,archiveddisplayNamestringrequiredlegalNamestringrequirednullableidentifierSchemestringrequirednullableidentifierstringrequirednullablegstNumberstringrequirednullablewebsitestringrequirednullablenotesstringrequirednullableinvoiceNotesstringrequirednullableorganisationIdstringrequirednullablereceivesInvoicesbooleanrequiredaddressesarray of objectsrequiredShow 12 child attributesHide child attributes
idstringrequiredlabelstringtypestringrequiredOne of:
BILLING,DELIVERY,POSTAL,PHYSICAL,REMITTANCE,OTHERattentionTostringaddressLinesarray of stringsrequiredsublocalitystringlocalitystringadministrativeAreastringpostalCodestringsortingCodestringcountryCodestringrequiredisInvoiceDefaultbooleanrequired
phonesarray of objectsrequiredShow 4 child attributesHide child attributes
idstringrequiredlabelstringnumberstringrequiredisPrimarybooleanrequired
organisationobjectrequirednullableShow 2 child attributesHide child attributes
idstringrequireddisplayNamestringrequired
createdAtstring (date-time)requiredupdatedAtstring (date-time)requiredarchivedAtstring (date-time)requirednullable
linkedInvoiceCountnumberrequired
400Invalid ID401Unauthorized.403Insufficient workspace role or entity permission.404Contact or entity not found.500Internal server error.
const { data } = await prosaic.contacts.update(entityId, contactId, {
displayName: 'Example Ltd',
email: {
email: 'accounts@example.com',
},
people: [
{
receivesInvoices: true,
id: 'ID',
email: 'accounts@example.com',
label: 'string',
displayName: 'Example Ltd',
},
],
phones: [
{
id: 'ID',
number: 'string',
},
],
addresses: [
{
id: 'ID',
type: 'BILLING',
addressLines: ['string'],
countryCode: 'COUNTRY_CODE',
},
],
linkPastInvoices: true,
legalName: 'Example Ltd',
identifierScheme: 'string',
identifier: 'string',
gstNumber: 'string',
website: 'string',
notes: 'string',
invoiceNotes: 'string',
});curl -X PATCH https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts/$CONTACT_ID \
-H "Authorization: Bearer $PROSAIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"displayName": "Example Ltd",
"email": {
"email": "accounts@example.com"
},
"people": [
{
"receivesInvoices": true,
"id": "ID",
"email": "accounts@example.com",
"label": "string",
"displayName": "Example Ltd"
}
],
"phones": [
{
"id": "ID",
"number": "string"
}
],
"addresses": [
{
"id": "ID",
"type": "BILLING",
"addressLines": [
"string"
],
"countryCode": "COUNTRY_CODE"
}
],
"linkPastInvoices": true,
"legalName": "Example Ltd",
"identifierScheme": "string",
"identifier": "string",
"gstNumber": "string",
"website": "string",
"notes": "string",
"invoiceNotes": "string"
}'Restore a contact
/api/public/v1/entities/{entityId}/contacts/{contactId}/restoreSDK: prosaic.contacts.restore(entityId, contactId, params)
Restores an archived contact and optionally the people archived with the same business operation.
Path parameters
entityIdstringrequiredcontactIdstringrequired
Request body
application/json
restorePeopleboolean
Responses
200 Successful response
statusstringrequiredOne of:
restored
400Invalid contact ID401Unauthorized.403Insufficient workspace role or entity permission.404Contact or entity not found.500Internal server error.
const result = await prosaic.contacts.restore(entityId, contactId, {
restorePeople: true,
});curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts/$CONTACT_ID/restore \
-H "Authorization: Bearer $PROSAIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"restorePeople": true
}'Delete a contact
/api/public/v1/entities/{entityId}/contacts/{contactId}SDK: prosaic.contacts.del(entityId, contactId)
Soft-deletes an active contact that has no invoice history.
Path parameters
entityIdstringrequiredcontactIdstringrequired
Responses
200 Successful response
statusstringrequiredOne of:
last-person,deleted,has-history
400Invalid contact ID.401Unauthorized.403Insufficient workspace role or entity permission.404Contact or entity not found.409Contact has invoice history or removal would leave a business without a person to invoice.500Internal server error.
const result = await prosaic.contacts.del(entityId, contactId);curl -X DELETE https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts/$CONTACT_ID \
-H "Authorization: Bearer $PROSAIC_API_KEY"Archive a contact
/api/public/v1/entities/{entityId}/contacts/{contactId}/archiveSDK: prosaic.contacts.archive(entityId, contactId, params)
Archives an active contact, optionally archiving a business's people with it.
Path parameters
entityIdstringrequiredcontactIdstringrequired
Request body
application/json
archivePeopleboolean
Responses
200 Successful response
statusstringrequiredOne of:
archived,last-person
400Invalid contact ID401Unauthorized.403Insufficient workspace role or entity permission.404Contact or entity not found.409Archiving would leave a live business without a person to invoice.500Internal server error.
const result = await prosaic.contacts.archive(entityId, contactId, {
archivePeople: true,
});curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts/$CONTACT_ID/archive \
-H "Authorization: Bearer $PROSAIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"archivePeople": true
}'