# Contacts

> Customers and suppliers: create, update, archive, restore and delete them.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## 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

- `entityId` (string)
- `type` (string): One of: `BUSINESS`, `INDIVIDUAL`.
- `status` (string): One of: `active`, `archived`, `all`.
- `updatedSince` (string)
- `page` (integer): Default: `1`.
- `pageSize` (integer): Default: `100`.

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
  - `pagination` (object, required)
    - `currentPage` (number, required)
    - `pageSize` (number, required)
    - `totalCount` (number, required)
    - `totalPages` (number, required)
    - `hasNextPage` (boolean, required)
    - `hasPreviousPage` (boolean, required)
- `400`: Invalid query parameters.
- `401`: Unauthorized.
- `403`: Insufficient role or token scope.
- `500`: Internal server error.

### Example (Node SDK)

```ts
const page = await prosaic.contacts.list();
```

### Example (curl)

```bash
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

- `entityId` (string, required)
- `contactId` (string, required)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - One of — type: BUSINESS:
      - `type` (string, required): One of: `BUSINESS`.
      - `people` (array of objects, required)
        - `id` (string, required)
        - `displayName` (string, required)
        - `receivesInvoices` (boolean, required)
        - `status` (string, required): One of: `active`, `archived`.
        - `archivedAt` (string, date-time, nullable, required)
        - `emails` (array of objects, required)
          - `id` (string, required)
          - `email` (string, required)
          - `label` (string, nullable, required)
      - `id` (string, required)
      - `workspaceId` (string, required)
      - `entityId` (string, required)
      - `status` (string, required): One of: `active`, `archived`.
      - `displayName` (string, required)
      - `legalName` (string, nullable, required)
      - `identifierScheme` (string, nullable, required)
      - `identifier` (string, nullable, required)
      - `gstNumber` (string, nullable, required)
      - `website` (string, nullable, required)
      - `notes` (string, nullable, required)
      - `invoiceNotes` (string, nullable, required)
      - `organisationId` (string, nullable, required)
      - `receivesInvoices` (boolean, required)
      - `addresses` (array of objects, required)
        - `id` (string, required)
        - `label` (string)
        - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`.
        - `attentionTo` (string)
        - `addressLines` (array of strings, required)
        - `sublocality` (string)
        - `locality` (string)
        - `administrativeArea` (string)
        - `postalCode` (string)
        - `sortingCode` (string)
        - `countryCode` (string, required)
        - `isInvoiceDefault` (boolean, required)
      - `phones` (array of objects, required)
        - `id` (string, required)
        - `label` (string)
        - `number` (string, required)
        - `isPrimary` (boolean, required)
      - `organisation` (object, nullable, required)
        - `id` (string, required)
        - `displayName` (string, required)
      - `createdAt` (string, date-time, required)
      - `updatedAt` (string, date-time, required)
      - `archivedAt` (string, date-time, nullable, required)
    - One of — type: INDIVIDUAL:
      - `type` (string, required): One of: `INDIVIDUAL`.
      - `emails` (array of objects, required)
        - `id` (string, required)
        - `email` (string, required)
        - `label` (string, nullable, required)
      - `id` (string, required)
      - `workspaceId` (string, required)
      - `entityId` (string, required)
      - `status` (string, required): One of: `active`, `archived`.
      - `displayName` (string, required)
      - `legalName` (string, nullable, required)
      - `identifierScheme` (string, nullable, required)
      - `identifier` (string, nullable, required)
      - `gstNumber` (string, nullable, required)
      - `website` (string, nullable, required)
      - `notes` (string, nullable, required)
      - `invoiceNotes` (string, nullable, required)
      - `organisationId` (string, nullable, required)
      - `receivesInvoices` (boolean, required)
      - `addresses` (array of objects, required)
        - `id` (string, required)
        - `label` (string)
        - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`.
        - `attentionTo` (string)
        - `addressLines` (array of strings, required)
        - `sublocality` (string)
        - `locality` (string)
        - `administrativeArea` (string)
        - `postalCode` (string)
        - `sortingCode` (string)
        - `countryCode` (string, required)
        - `isInvoiceDefault` (boolean, required)
      - `phones` (array of objects, required)
        - `id` (string, required)
        - `label` (string)
        - `number` (string, required)
        - `isPrimary` (boolean, required)
      - `organisation` (object, nullable, required)
        - `id` (string, required)
        - `displayName` (string, required)
      - `createdAt` (string, date-time, required)
      - `updatedAt` (string, date-time, required)
      - `archivedAt` (string, date-time, nullable, required)
- `400`: Invalid contact ID.
- `401`: Unauthorized.
- `403`: Insufficient workspace role.
- `404`: Contact or entity not found.
- `500`: Internal server error.

### Example (Node SDK)

```ts
const { data } = await prosaic.contacts.retrieve(entityId, contactId);
```

### Example (curl)

```bash
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

- `entityId` (string, required)

### Request body

Content type: `application/json`

- One of — With displayName, type:
  - `displayName` (string, required)
  - `type` (string, required): One of: `BUSINESS`, `INDIVIDUAL`.
  - `email` (object)
    - `email` (string, required)
    - `label` (string)
  - `people` (array of objects)
    - `receivesInvoices` (boolean)
    - `id` (string)
    - `email` (string)
    - `label` (string)
    - `displayName` (string)
  - `phones` (array of objects)
    - `id` (string, required)
    - `number` (string, required)
    - `label` (string)
    - `isPrimary` (boolean)
  - `addresses` (array of objects)
    - `id` (string, required)
    - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`.
    - `addressLines` (array of strings, required)
    - `countryCode` (string, required)
    - `label` (string)
    - `attentionTo` (string)
    - `sublocality` (string)
    - `locality` (string)
    - `administrativeArea` (string)
    - `postalCode` (string)
    - `sortingCode` (string)
    - `isInvoiceDefault` (boolean)
  - `linkPastInvoices` (boolean)
  - `legalName` (string)
  - `identifierScheme` (string)
  - `identifier` (string)
  - `gstNumber` (string)
  - `website` (string)
  - `notes` (string)
  - `invoiceNotes` (string)
- One of — With people:
  - `people` (array of objects, required)
    - `receivesInvoices` (boolean)
    - `id` (string)
    - `email` (string)
    - `label` (string)
    - `displayName` (string)

### Responses

- `201`: Successful response
  - `data` (object, required)
    - One of — type: BUSINESS:
      - `type` (string, required): One of: `BUSINESS`.
      - `people` (array of objects, required)
        - `id` (string, required)
        - `displayName` (string, required)
        - `receivesInvoices` (boolean, required)
        - `status` (string, required): One of: `active`, `archived`.
        - `archivedAt` (string, date-time, nullable, required)
        - `emails` (array of objects, required)
          - `id` (string, required)
          - `email` (string, required)
          - `label` (string, nullable, required)
      - `id` (string, required)
      - `workspaceId` (string, required)
      - `entityId` (string, required)
      - `status` (string, required): One of: `active`, `archived`.
      - `displayName` (string, required)
      - `legalName` (string, nullable, required)
      - `identifierScheme` (string, nullable, required)
      - `identifier` (string, nullable, required)
      - `gstNumber` (string, nullable, required)
      - `website` (string, nullable, required)
      - `notes` (string, nullable, required)
      - `invoiceNotes` (string, nullable, required)
      - `organisationId` (string, nullable, required)
      - `receivesInvoices` (boolean, required)
      - `addresses` (array of objects, required)
        - `id` (string, required)
        - `label` (string)
        - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`.
        - `attentionTo` (string)
        - `addressLines` (array of strings, required)
        - `sublocality` (string)
        - `locality` (string)
        - `administrativeArea` (string)
        - `postalCode` (string)
        - `sortingCode` (string)
        - `countryCode` (string, required)
        - `isInvoiceDefault` (boolean, required)
      - `phones` (array of objects, required)
        - `id` (string, required)
        - `label` (string)
        - `number` (string, required)
        - `isPrimary` (boolean, required)
      - `organisation` (object, nullable, required)
        - `id` (string, required)
        - `displayName` (string, required)
      - `createdAt` (string, date-time, required)
      - `updatedAt` (string, date-time, required)
      - `archivedAt` (string, date-time, nullable, required)
    - One of — type: INDIVIDUAL:
      - `type` (string, required): One of: `INDIVIDUAL`.
      - `emails` (array of objects, required)
        - `id` (string, required)
        - `email` (string, required)
        - `label` (string, nullable, required)
      - `id` (string, required)
      - `workspaceId` (string, required)
      - `entityId` (string, required)
      - `status` (string, required): One of: `active`, `archived`.
      - `displayName` (string, required)
      - `legalName` (string, nullable, required)
      - `identifierScheme` (string, nullable, required)
      - `identifier` (string, nullable, required)
      - `gstNumber` (string, nullable, required)
      - `website` (string, nullable, required)
      - `notes` (string, nullable, required)
      - `invoiceNotes` (string, nullable, required)
      - `organisationId` (string, nullable, required)
      - `receivesInvoices` (boolean, required)
      - `addresses` (array of objects, required)
        - `id` (string, required)
        - `label` (string)
        - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`.
        - `attentionTo` (string)
        - `addressLines` (array of strings, required)
        - `sublocality` (string)
        - `locality` (string)
        - `administrativeArea` (string)
        - `postalCode` (string)
        - `sortingCode` (string)
        - `countryCode` (string, required)
        - `isInvoiceDefault` (boolean, required)
      - `phones` (array of objects, required)
        - `id` (string, required)
        - `label` (string)
        - `number` (string, required)
        - `isPrimary` (boolean, required)
      - `organisation` (object, nullable, required)
        - `id` (string, required)
        - `displayName` (string, required)
      - `createdAt` (string, date-time, required)
      - `updatedAt` (string, date-time, required)
      - `archivedAt` (string, date-time, nullable, required)
  - `linkedInvoiceCount` (number, required)
- `400`: Invalid JSON
- `401`: Unauthorized.
- `403`: Insufficient workspace role or entity permission.
- `404`: Entity not found.
- `500`: Internal server error.

### Example (Node SDK)

```ts
const { data } = await prosaic.contacts.create(entityId, {
  displayName: 'Example Ltd',
  type: 'BUSINESS',
});
```

### Example (curl)

```bash
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

- `entityId` (string, required)
- `contactId` (string, required)

### Request body

Content type: `application/json`

- `displayName` (string)
- `email` (object, nullable)
  - `email` (string, required)
  - `label` (string, nullable)
- `people` (array of objects)
  - `receivesInvoices` (boolean)
  - `id` (string)
  - `email` (string)
  - `label` (string)
  - `displayName` (string)
- `phones` (array of objects)
  - `id` (string, required)
  - `number` (string, required)
  - `label` (string)
  - `isPrimary` (boolean)
- `addresses` (array of objects)
  - `id` (string, required)
  - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`.
  - `addressLines` (array of strings, required)
  - `countryCode` (string, required)
  - `label` (string)
  - `attentionTo` (string)
  - `sublocality` (string)
  - `locality` (string)
  - `administrativeArea` (string)
  - `postalCode` (string)
  - `sortingCode` (string)
  - `isInvoiceDefault` (boolean)
- `linkPastInvoices` (boolean)
- `legalName` (string, nullable)
- `identifierScheme` (string, nullable)
- `identifier` (string, nullable)
- `gstNumber` (string, nullable)
- `website` (string, nullable)
- `notes` (string, nullable)
- `invoiceNotes` (string, nullable)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - One of — type: BUSINESS:
      - `type` (string, required): One of: `BUSINESS`.
      - `people` (array of objects, required)
        - `id` (string, required)
        - `displayName` (string, required)
        - `receivesInvoices` (boolean, required)
        - `status` (string, required): One of: `active`, `archived`.
        - `archivedAt` (string, date-time, nullable, required)
        - `emails` (array of objects, required)
          - `id` (string, required)
          - `email` (string, required)
          - `label` (string, nullable, required)
      - `id` (string, required)
      - `workspaceId` (string, required)
      - `entityId` (string, required)
      - `status` (string, required): One of: `active`, `archived`.
      - `displayName` (string, required)
      - `legalName` (string, nullable, required)
      - `identifierScheme` (string, nullable, required)
      - `identifier` (string, nullable, required)
      - `gstNumber` (string, nullable, required)
      - `website` (string, nullable, required)
      - `notes` (string, nullable, required)
      - `invoiceNotes` (string, nullable, required)
      - `organisationId` (string, nullable, required)
      - `receivesInvoices` (boolean, required)
      - `addresses` (array of objects, required)
        - `id` (string, required)
        - `label` (string)
        - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`.
        - `attentionTo` (string)
        - `addressLines` (array of strings, required)
        - `sublocality` (string)
        - `locality` (string)
        - `administrativeArea` (string)
        - `postalCode` (string)
        - `sortingCode` (string)
        - `countryCode` (string, required)
        - `isInvoiceDefault` (boolean, required)
      - `phones` (array of objects, required)
        - `id` (string, required)
        - `label` (string)
        - `number` (string, required)
        - `isPrimary` (boolean, required)
      - `organisation` (object, nullable, required)
        - `id` (string, required)
        - `displayName` (string, required)
      - `createdAt` (string, date-time, required)
      - `updatedAt` (string, date-time, required)
      - `archivedAt` (string, date-time, nullable, required)
    - One of — type: INDIVIDUAL:
      - `type` (string, required): One of: `INDIVIDUAL`.
      - `emails` (array of objects, required)
        - `id` (string, required)
        - `email` (string, required)
        - `label` (string, nullable, required)
      - `id` (string, required)
      - `workspaceId` (string, required)
      - `entityId` (string, required)
      - `status` (string, required): One of: `active`, `archived`.
      - `displayName` (string, required)
      - `legalName` (string, nullable, required)
      - `identifierScheme` (string, nullable, required)
      - `identifier` (string, nullable, required)
      - `gstNumber` (string, nullable, required)
      - `website` (string, nullable, required)
      - `notes` (string, nullable, required)
      - `invoiceNotes` (string, nullable, required)
      - `organisationId` (string, nullable, required)
      - `receivesInvoices` (boolean, required)
      - `addresses` (array of objects, required)
        - `id` (string, required)
        - `label` (string)
        - `type` (string, required): One of: `BILLING`, `DELIVERY`, `POSTAL`, `PHYSICAL`, `REMITTANCE`, `OTHER`.
        - `attentionTo` (string)
        - `addressLines` (array of strings, required)
        - `sublocality` (string)
        - `locality` (string)
        - `administrativeArea` (string)
        - `postalCode` (string)
        - `sortingCode` (string)
        - `countryCode` (string, required)
        - `isInvoiceDefault` (boolean, required)
      - `phones` (array of objects, required)
        - `id` (string, required)
        - `label` (string)
        - `number` (string, required)
        - `isPrimary` (boolean, required)
      - `organisation` (object, nullable, required)
        - `id` (string, required)
        - `displayName` (string, required)
      - `createdAt` (string, date-time, required)
      - `updatedAt` (string, date-time, required)
      - `archivedAt` (string, date-time, nullable, required)
  - `linkedInvoiceCount` (number, required)
- `400`: Invalid ID
- `401`: Unauthorized.
- `403`: Insufficient workspace role or entity permission.
- `404`: Contact or entity not found.
- `500`: Internal server error.

### Example (Node SDK)

```ts
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',
});
```

### Example (curl)

```bash
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

- `entityId` (string, required)
- `contactId` (string, required)

### Request body

Content type: `application/json`

- `restorePeople` (boolean)

### Responses

- `200`: Successful response
  - `status` (string, required): 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.

### Example (Node SDK)

```ts
const result = await prosaic.contacts.restore(entityId, contactId, {
  restorePeople: true,
});
```

### Example (curl)

```bash
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

`DELETE /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

- `entityId` (string, required)
- `contactId` (string, required)

### Responses

- `200`: Successful response
  - `status` (string, required): 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.

### Example (Node SDK)

```ts
const result = await prosaic.contacts.del(entityId, contactId);
```

### Example (curl)

```bash
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

- `entityId` (string, required)
- `contactId` (string, required)

### Request body

Content type: `application/json`

- `archivePeople` (boolean)

### Responses

- `200`: Successful response
  - `status` (string, required): 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.

### Example (Node SDK)

```ts
const result = await prosaic.contacts.archive(entityId, contactId, {
  archivePeople: true,
});
```

### Example (curl)

```bash
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
  }'
```