Customer contacts

A customer contact is a user associated with a customer in your Accounts Receivable (AR) system. Customer contacts can sign in to the BILL web app to view invoices, make payments, and manage their account. You can create multiple contacts for a customer to manage different points of contact, such as purchasing, accounts payable, or finance departments.

See the /v3/customers/{customerId}/contacts API for the complete list of available operations.

Create a customer contact

In your POST /v3/customers/{customerId}/contacts request, a customer contact is created with the specified details.

Field	Description
`firstName`	Customer first name
`lastName`	Customer last name
`email`	Customer email address. The email address must be unique for the customer.
`phone`	Customer phone number
`altPhone`	Customer alternate phone number. Use this field to sync with your accounting system.
`alternateEmail`	Customer alternate email address. The customer cannot use this email address to sign in to the BILL web app.

See POST /v3/customers/{customerId}/contacts for more information.

Sample request

In this cURL example, a customer contact is created with the specified details. The email is set as the contact email address for the customer. The optional alternateEmail is added to receive payment-related notifications at a separate email address.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/customers/{customerId}/contacts' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "firstName": "Check",
  "lastName": "Mailworth",
  "email": "[email protected]",
  "phone": "9998887654",
  "altPhone": "5559876543"
  "alternateEmail": "[email protected]"
}'

Response

In the response, a BILL-generated customer contact id is available. The value begins with cpu. You can use this customer contact id for other customer contact operations.

{
  "id": "cpu02DVXKMFYWYOO2w18",
  "archived": false,
  "customerId": "{customer_id}",
  "firstName": "Check",
  "lastName": "Mailworth",
  "email": "[email protected]",
  "phone": "9998887654",
  "altPhone": "5559876543,
  "alternateEmail": "[email protected]",
  "createdTime": "2026-05-20T11:55:05.000+0000",
  "updatedTime": "2026-05-20T11:55:05.000+0000"
}

Get list of customer contacts

Use GET /v3/customers/{customerId}/contacts to get a list of customer contacts for a customer. By default, you get 20 results on one page of results. Set max in your request to get up to 100 results on one page.

See Search operations with lists to learn about pagination, sorting, and filtering.

Sample request

In this cURL example, a list of customer contacts is returned for a customer.

curl --request GET \
--url 'https://gateway.stage.bill.com/connect/v3/customers/{customerId}/contacts?max=10&sort=firstName:asc' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}'

Response

In the response, the customer contacts for the customer are available.

{
  "nextPage": null,
  "prevPage": null,
  "results": [
    {
      "id": "cpu02DVXKMFYWYOO2w18",
      "archived": false,
      "customerId": "{customer_id}",
      "firstName": "Check",
      "lastName": "Mailworth",
      "email": "[email protected]",
      "phone": "9998887654",
      "altPhone": "5559876543",
      "alternateEmail": "[email protected]",
      "createdTime": "2026-05-20T11:55:05.000+0000",
      "updatedTime": "2026-05-20T11:55:05.000+0000"
    
  ]
}

See GET /v3/customers/{customerId}/contacts for more information.

Get customer contact details

Use GET /v3/customers/{customerId}/contacts/{contactId} to get details about an existing customer contact.

Sample request

In this cURL example, the details of an existing customer contact are returned using the customer contact id.

curl --request GET \
--url 'https://gateway.stage.bill.com/connect/v3/customers/{customerId}/contacts/{contactId}' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}'

Response

In the response, the customer contact details are available.

{
  "id": "cpu02DVXKMFYWYOO2w18",
  "archived": false,
  "customerId": "{customer_id}",
  "firstName": "Check",
  "lastName": "Mailworth",
  "email": "[email protected]",
  "phone": "9998887654",
  "altPhone": "5559876543",
  "alternateEmail": "[email protected]",
  "createdTime": "2026-05-20T11:55:05.000+0000",
  "updatedTime": "2026-05-20T11:55:05.000+0000"
}

See GET /v3/customers/{customerId}/contacts/{contactId} for more information.

Update a customer contact

In your PATCH /v3/customers/{customerId}/contacts/{contactId} request, set the fields you want to update.

Sample request

In this cURL example, the firstName and phone of an existing customer contact are updated.

curl --request PATCH \
--url 'https://gateway.stage.bill.com/connect/v3/customers/{customerId}/contacts/{contactId}' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "firstName": "Adam",
  "phone": "9998887655"
}'

Response

In the response, the updated customer contact details are available.

{
  "id": "cpu02DVXKMFYWYOO2w18",
  "archived": false,
  "customerId": "{customer_id}",
  "firstName": "Adam",
  "lastName": "Mailworth",
  "email": "[email protected]",
  "phone": "9998887655",
  "altPhone": "5559876543",
  "alternateEmail": "[email protected]",
  "createdTime": "2026-05-20T11:55:05.000+0000",
  "updatedTime": "2026-05-20T11:55:05.000+0000"
}

See PATCH /v3/customers/{customerId}/contacts/{contactId} for more information.

Archive a customer contact

Use POST v3/customers/{customerId}/contacts/{contactId}/archive to archive a customer contact. In the response, archived is set as true.

Sample request

In this cURL example, an existing customer contact is archived using the customer contact id.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/customers/{customerId}/contacts/{contactId}/archive' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}'

Response

In the response, archived is set as true.

{
  "id": "cpu02DVXKMFYWYOO2w18",
  "archived": true,
  "customerId": "{customer_id}",
  "firstName": "Check",
  "lastName": "Mailworth",
  "email": "[email protected]",
  "phone": "9998887654",
  "altPhone": "5559876543",
  "alternateEmail": "[email protected]",
  "createdTime": "2026-05-20T11:55:05.000+0000",
  "updatedTime": "2026-05-20T11:55:05.000+0000"
}

See POST v3/customers/{customerId}/contacts/{contactId}/archive for more information.

Restore a customer contact

Use POST /v3/customers/{customerId}/contacts/{contactId}/restore to restore an archived customer contact. In the response, archived is set as false.

You can perform any valid BILL operation on a restored customer contact. There is no change when you restore a customer contact that is not archived.

Sample request

In this cURL example, an archived customer contact is restored using the customer contact id.

curl --request POST \
--url 'https://gateway.stage.bill.com/connect/v3/customers/{customerId}/contacts/{contactId}/restore' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}'

Response

In the response, archived is set as false.

{
  "id": "cpu02DVXKMFYWYOO2w18",
  "archived": false,
  "customerId": "{customer_id}",
  "firstName": "Check",
  "lastName": "Mailworth",
  "email": "[email protected]",
  "phone": "9998887654",
  "altPhone": "5559876543",
  "alternateEmail": "[email protected]",
  "createdTime": "2026-05-20T11:55:05.000+0000",
  "updatedTime": "2026-05-20T11:55:05.000+0000"
}

See POST /v3/customers/{customerId}/contacts/{contactId}/restore for more information.