All API resources
API reference

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

GET/api/public/v1/contacts

SDK: prosaic.contacts.list(params)

Returns non-deleted contacts from entities visible in the active workspace.

Query parameters

  • entityIdstring
  • typestring

    One of: BUSINESS, INDIVIDUAL

  • statusstring

    One of: active, archived, all

  • updatedSincestring
  • pageinteger

    Default: 1

  • pageSizeinteger

    Default: 100

Responses

200 Successful response

  • dataarray of objectsrequired
  • paginationobjectrequired
    Show 6 child attributes
    • currentPagenumberrequired
    • pageSizenumberrequired
    • totalCountnumberrequired
    • totalPagesnumberrequired
    • hasNextPagebooleanrequired
    • hasPreviousPagebooleanrequired
  • 400 Invalid query parameters.
  • 401 Unauthorized.
  • 403 Insufficient role or token scope.
  • 500 Internal server error.
Node SDK
const page = await prosaic.contacts.list();
curl
curl https://app.prosaic.works/api/public/v1/contacts \
  -H "Authorization: Bearer $PROSAIC_API_KEY"

Get a contact

GET/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

  • entityIdstringrequired
  • contactIdstringrequired

Responses

200 Successful response

  • dataobjectrequired
    One of: type: BUSINESS
    • typestringrequired

      One of: BUSINESS

    • peoplearray of objectsrequired
      Show 6 child attributes
      • idstringrequired
      • displayNamestringrequired
      • receivesInvoicesbooleanrequired
      • statusstringrequired

        One of: active, archived

      • archivedAtstring (date-time)requirednullable
      • emailsarray of objectsrequired
        Show 3 child attributes
        • idstringrequired
        • emailstringrequired
        • labelstringrequirednullable
    • idstringrequired
    • workspaceIdstringrequired
    • entityIdstringrequired
    • statusstringrequired

      One of: active, archived

    • displayNamestringrequired
    • legalNamestringrequirednullable
    • identifierSchemestringrequirednullable
    • identifierstringrequirednullable
    • gstNumberstringrequirednullable
    • websitestringrequirednullable
    • notesstringrequirednullable
    • invoiceNotesstringrequirednullable
    • organisationIdstringrequirednullable
    • receivesInvoicesbooleanrequired
    • addressesarray of objectsrequired
      Show 12 child attributes
      • idstringrequired
      • labelstring
      • typestringrequired

        One of: BILLING, DELIVERY, POSTAL, PHYSICAL, REMITTANCE, OTHER

      • attentionTostring
      • addressLinesarray of stringsrequired
      • sublocalitystring
      • localitystring
      • administrativeAreastring
      • postalCodestring
      • sortingCodestring
      • countryCodestringrequired
      • isInvoiceDefaultbooleanrequired
    • phonesarray of objectsrequired
      Show 4 child attributes
      • idstringrequired
      • labelstring
      • numberstringrequired
      • isPrimarybooleanrequired
    • organisationobjectrequirednullable
      Show 2 child attributes
      • idstringrequired
      • displayNamestringrequired
    • createdAtstring (date-time)required
    • updatedAtstring (date-time)required
    • archivedAtstring (date-time)requirednullable
    One of: type: INDIVIDUAL
    • typestringrequired

      One of: INDIVIDUAL

    • emailsarray of objectsrequired
      Show 3 child attributes
      • idstringrequired
      • emailstringrequired
      • labelstringrequirednullable
    • idstringrequired
    • workspaceIdstringrequired
    • entityIdstringrequired
    • statusstringrequired

      One of: active, archived

    • displayNamestringrequired
    • legalNamestringrequirednullable
    • identifierSchemestringrequirednullable
    • identifierstringrequirednullable
    • gstNumberstringrequirednullable
    • websitestringrequirednullable
    • notesstringrequirednullable
    • invoiceNotesstringrequirednullable
    • organisationIdstringrequirednullable
    • receivesInvoicesbooleanrequired
    • addressesarray of objectsrequired
      Show 12 child attributes
      • idstringrequired
      • labelstring
      • typestringrequired

        One of: BILLING, DELIVERY, POSTAL, PHYSICAL, REMITTANCE, OTHER

      • attentionTostring
      • addressLinesarray of stringsrequired
      • sublocalitystring
      • localitystring
      • administrativeAreastring
      • postalCodestring
      • sortingCodestring
      • countryCodestringrequired
      • isInvoiceDefaultbooleanrequired
    • phonesarray of objectsrequired
      Show 4 child attributes
      • idstringrequired
      • labelstring
      • numberstringrequired
      • isPrimarybooleanrequired
    • organisationobjectrequirednullable
      Show 2 child attributes
      • idstringrequired
      • displayNamestringrequired
    • createdAtstring (date-time)required
    • updatedAtstring (date-time)required
    • archivedAtstring (date-time)requirednullable
  • 400 Invalid contact ID.
  • 401 Unauthorized.
  • 403 Insufficient workspace role.
  • 404 Contact or entity not found.
  • 500 Internal server error.
Node SDK
const { data } = await prosaic.contacts.retrieve(entityId, contactId);
curl
curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/contacts/$CONTACT_ID \
  -H "Authorization: Bearer $PROSAIC_API_KEY"

Create a contact

POST/api/public/v1/entities/{entityId}/contacts

SDK: 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

  • displayNamestringrequired
  • typestringrequired

    One of: BUSINESS, INDIVIDUAL

  • emailobject
    Show 2 child attributes
    • emailstringrequired
    • labelstring
  • peoplearray of objects
    Show 5 child attributes
    • receivesInvoicesboolean
    • idstring
    • emailstring
    • labelstring
    • displayNamestring
  • phonesarray of objects
    Show 4 child attributes
    • idstringrequired
    • numberstringrequired
    • labelstring
    • isPrimaryboolean
  • addressesarray of objects
    Show 12 child attributes
    • idstringrequired
    • typestringrequired

      One of: BILLING, DELIVERY, POSTAL, PHYSICAL, REMITTANCE, OTHER

    • addressLinesarray of stringsrequired
    • countryCodestringrequired
    • labelstring
    • attentionTostring
    • sublocalitystring
    • localitystring
    • administrativeAreastring
    • postalCodestring
    • sortingCodestring
    • isInvoiceDefaultboolean
  • linkPastInvoicesboolean
  • legalNamestring
  • identifierSchemestring
  • identifierstring
  • gstNumberstring
  • websitestring
  • notesstring
  • invoiceNotesstring

One of — With people

  • peoplearray of objectsrequired
    Show 5 child attributes
    • receivesInvoicesboolean
    • idstring
    • emailstring
    • labelstring
    • displayNamestring

Responses

201 Successful response

  • dataobjectrequired
    One of: type: BUSINESS
    • typestringrequired

      One of: BUSINESS

    • peoplearray of objectsrequired
      Show 6 child attributes
      • idstringrequired
      • displayNamestringrequired
      • receivesInvoicesbooleanrequired
      • statusstringrequired

        One of: active, archived

      • archivedAtstring (date-time)requirednullable
      • emailsarray of objectsrequired
        Show 3 child attributes
        • idstringrequired
        • emailstringrequired
        • labelstringrequirednullable
    • idstringrequired
    • workspaceIdstringrequired
    • entityIdstringrequired
    • statusstringrequired

      One of: active, archived

    • displayNamestringrequired
    • legalNamestringrequirednullable
    • identifierSchemestringrequirednullable
    • identifierstringrequirednullable
    • gstNumberstringrequirednullable
    • websitestringrequirednullable
    • notesstringrequirednullable
    • invoiceNotesstringrequirednullable
    • organisationIdstringrequirednullable
    • receivesInvoicesbooleanrequired
    • addressesarray of objectsrequired
      Show 12 child attributes
      • idstringrequired
      • labelstring
      • typestringrequired

        One of: BILLING, DELIVERY, POSTAL, PHYSICAL, REMITTANCE, OTHER

      • attentionTostring
      • addressLinesarray of stringsrequired
      • sublocalitystring
      • localitystring
      • administrativeAreastring
      • postalCodestring
      • sortingCodestring
      • countryCodestringrequired
      • isInvoiceDefaultbooleanrequired
    • phonesarray of objectsrequired
      Show 4 child attributes
      • idstringrequired
      • labelstring
      • numberstringrequired
      • isPrimarybooleanrequired
    • organisationobjectrequirednullable
      Show 2 child attributes
      • idstringrequired
      • displayNamestringrequired
    • createdAtstring (date-time)required
    • updatedAtstring (date-time)required
    • archivedAtstring (date-time)requirednullable
    One of: type: INDIVIDUAL
    • typestringrequired

      One of: INDIVIDUAL

    • emailsarray of objectsrequired
      Show 3 child attributes
      • idstringrequired
      • emailstringrequired
      • labelstringrequirednullable
    • idstringrequired
    • workspaceIdstringrequired
    • entityIdstringrequired
    • statusstringrequired

      One of: active, archived

    • displayNamestringrequired
    • legalNamestringrequirednullable
    • identifierSchemestringrequirednullable
    • identifierstringrequirednullable
    • gstNumberstringrequirednullable
    • websitestringrequirednullable
    • notesstringrequirednullable
    • invoiceNotesstringrequirednullable
    • organisationIdstringrequirednullable
    • receivesInvoicesbooleanrequired
    • addressesarray of objectsrequired
      Show 12 child attributes
      • idstringrequired
      • labelstring
      • typestringrequired

        One of: BILLING, DELIVERY, POSTAL, PHYSICAL, REMITTANCE, OTHER

      • attentionTostring
      • addressLinesarray of stringsrequired
      • sublocalitystring
      • localitystring
      • administrativeAreastring
      • postalCodestring
      • sortingCodestring
      • countryCodestringrequired
      • isInvoiceDefaultbooleanrequired
    • phonesarray of objectsrequired
      Show 4 child attributes
      • idstringrequired
      • labelstring
      • numberstringrequired
      • isPrimarybooleanrequired
    • organisationobjectrequirednullable
      Show 2 child attributes
      • idstringrequired
      • displayNamestringrequired
    • createdAtstring (date-time)required
    • updatedAtstring (date-time)required
    • archivedAtstring (date-time)requirednullable
  • linkedInvoiceCountnumberrequired
  • 400 Invalid JSON
  • 401 Unauthorized.
  • 403 Insufficient workspace role or entity permission.
  • 404 Entity not found.
  • 500 Internal server error.
Node SDK
const { data } = await prosaic.contacts.create(entityId, {
  displayName: 'Example Ltd',
  type: 'BUSINESS',
});
curl
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

PATCH/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

  • entityIdstringrequired
  • contactIdstringrequired

Request body

application/json

  • displayNamestring
  • emailobjectnullable
    Show 2 child attributes
    • emailstringrequired
    • labelstringnullable
  • peoplearray of objects
    Show 5 child attributes
    • receivesInvoicesboolean
    • idstring
    • emailstring
    • labelstring
    • displayNamestring
  • phonesarray of objects
    Show 4 child attributes
    • idstringrequired
    • numberstringrequired
    • labelstring
    • isPrimaryboolean
  • addressesarray of objects
    Show 12 child attributes
    • idstringrequired
    • typestringrequired

      One of: BILLING, DELIVERY, POSTAL, PHYSICAL, REMITTANCE, OTHER

    • addressLinesarray of stringsrequired
    • countryCodestringrequired
    • labelstring
    • attentionTostring
    • sublocalitystring
    • localitystring
    • administrativeAreastring
    • postalCodestring
    • sortingCodestring
    • isInvoiceDefaultboolean
  • linkPastInvoicesboolean
  • legalNamestringnullable
  • identifierSchemestringnullable
  • identifierstringnullable
  • gstNumberstringnullable
  • websitestringnullable
  • notesstringnullable
  • invoiceNotesstringnullable

Responses

200 Successful response

  • dataobjectrequired
    One of: type: BUSINESS
    • typestringrequired

      One of: BUSINESS

    • peoplearray of objectsrequired
      Show 6 child attributes
      • idstringrequired
      • displayNamestringrequired
      • receivesInvoicesbooleanrequired
      • statusstringrequired

        One of: active, archived

      • archivedAtstring (date-time)requirednullable
      • emailsarray of objectsrequired
        Show 3 child attributes
        • idstringrequired
        • emailstringrequired
        • labelstringrequirednullable
    • idstringrequired
    • workspaceIdstringrequired
    • entityIdstringrequired
    • statusstringrequired

      One of: active, archived

    • displayNamestringrequired
    • legalNamestringrequirednullable
    • identifierSchemestringrequirednullable
    • identifierstringrequirednullable
    • gstNumberstringrequirednullable
    • websitestringrequirednullable
    • notesstringrequirednullable
    • invoiceNotesstringrequirednullable
    • organisationIdstringrequirednullable
    • receivesInvoicesbooleanrequired
    • addressesarray of objectsrequired
      Show 12 child attributes
      • idstringrequired
      • labelstring
      • typestringrequired

        One of: BILLING, DELIVERY, POSTAL, PHYSICAL, REMITTANCE, OTHER

      • attentionTostring
      • addressLinesarray of stringsrequired
      • sublocalitystring
      • localitystring
      • administrativeAreastring
      • postalCodestring
      • sortingCodestring
      • countryCodestringrequired
      • isInvoiceDefaultbooleanrequired
    • phonesarray of objectsrequired
      Show 4 child attributes
      • idstringrequired
      • labelstring
      • numberstringrequired
      • isPrimarybooleanrequired
    • organisationobjectrequirednullable
      Show 2 child attributes
      • idstringrequired
      • displayNamestringrequired
    • createdAtstring (date-time)required
    • updatedAtstring (date-time)required
    • archivedAtstring (date-time)requirednullable
    One of: type: INDIVIDUAL
    • typestringrequired

      One of: INDIVIDUAL

    • emailsarray of objectsrequired
      Show 3 child attributes
      • idstringrequired
      • emailstringrequired
      • labelstringrequirednullable
    • idstringrequired
    • workspaceIdstringrequired
    • entityIdstringrequired
    • statusstringrequired

      One of: active, archived

    • displayNamestringrequired
    • legalNamestringrequirednullable
    • identifierSchemestringrequirednullable
    • identifierstringrequirednullable
    • gstNumberstringrequirednullable
    • websitestringrequirednullable
    • notesstringrequirednullable
    • invoiceNotesstringrequirednullable
    • organisationIdstringrequirednullable
    • receivesInvoicesbooleanrequired
    • addressesarray of objectsrequired
      Show 12 child attributes
      • idstringrequired
      • labelstring
      • typestringrequired

        One of: BILLING, DELIVERY, POSTAL, PHYSICAL, REMITTANCE, OTHER

      • attentionTostring
      • addressLinesarray of stringsrequired
      • sublocalitystring
      • localitystring
      • administrativeAreastring
      • postalCodestring
      • sortingCodestring
      • countryCodestringrequired
      • isInvoiceDefaultbooleanrequired
    • phonesarray of objectsrequired
      Show 4 child attributes
      • idstringrequired
      • labelstring
      • numberstringrequired
      • isPrimarybooleanrequired
    • organisationobjectrequirednullable
      Show 2 child attributes
      • idstringrequired
      • displayNamestringrequired
    • createdAtstring (date-time)required
    • updatedAtstring (date-time)required
    • archivedAtstring (date-time)requirednullable
  • linkedInvoiceCountnumberrequired
  • 400 Invalid ID
  • 401 Unauthorized.
  • 403 Insufficient workspace role or entity permission.
  • 404 Contact or entity not found.
  • 500 Internal server error.
Node SDK
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
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

POST/api/public/v1/entities/{entityId}/contacts/{contactId}/restore

SDK: prosaic.contacts.restore(entityId, contactId, params)

Restores an archived contact and optionally the people archived with the same business operation.

Path parameters

  • entityIdstringrequired
  • contactIdstringrequired

Request body

application/json

  • restorePeopleboolean

Responses

200 Successful response

  • statusstringrequired

    One of: restored

  • 400 Invalid contact ID
  • 401 Unauthorized.
  • 403 Insufficient workspace role or entity permission.
  • 404 Contact or entity not found.
  • 500 Internal server error.
Node SDK
const result = await prosaic.contacts.restore(entityId, contactId, {
  restorePeople: true,
});
curl
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

DEL/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

  • entityIdstringrequired
  • contactIdstringrequired

Responses

200 Successful response

  • statusstringrequired

    One of: last-person, deleted, has-history

  • 400 Invalid contact ID.
  • 401 Unauthorized.
  • 403 Insufficient workspace role or entity permission.
  • 404 Contact or entity not found.
  • 409 Contact has invoice history or removal would leave a business without a person to invoice.
  • 500 Internal server error.
Node SDK
const result = await prosaic.contacts.del(entityId, contactId);
curl
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

POST/api/public/v1/entities/{entityId}/contacts/{contactId}/archive

SDK: prosaic.contacts.archive(entityId, contactId, params)

Archives an active contact, optionally archiving a business's people with it.

Path parameters

  • entityIdstringrequired
  • contactIdstringrequired

Request body

application/json

  • archivePeopleboolean

Responses

200 Successful response

  • statusstringrequired

    One of: archived, last-person

  • 400 Invalid contact ID
  • 401 Unauthorized.
  • 403 Insufficient workspace role or entity permission.
  • 404 Contact or entity not found.
  • 409 Archiving would leave a live business without a person to invoice.
  • 500 Internal server error.
Node SDK
const result = await prosaic.contacts.archive(entityId, contactId, {
  archivePeople: true,
});
curl
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
  }'