Contacts API

Contacts are the people and organizations linked to your records: the artists credited on works, the buyers and consignees on sales and consignments, and the authors of press. Artworks reference their artists by contact ID in the artistIds field, so use these endpoints to turn those IDs into names, and to credit or uncredit a contact on a work. Every request needs an API key, as described in the API overview.

Your vault has its own contact record, which stands in for you or your studio. This record has self set to true, a field no other contact carries. Works can credit it like any other contact, but it can only be edited from vault settings, so the update and delete endpoints respond with a 409 for it.

List contacts

Get all the contacts in your vault.

GET /v0/contacts

curl https://api.valise.works/v0/contacts
  --header "Authorization: Bearer <API_KEY>"

Here’s an example response:

{
  "data": [
    {
      "id": "d2qv9c35i88kat3bkc7g",
      "name": "Jane Painter",
      "email": "jane@example.com",
      "notes": "Shares the studio on weekends.",
      "createdAt": "2024-09-06T11:17:15.150Z",
      "updatedAt": "2024-09-06T11:17:15.150Z"
    }
  ],
  "page": {
    "count": 1,
    "next": null
  }
}

The email and notes fields are empty strings when they haven’t been filled in. Your vault’s own contact also carries "self": true.

Get a contact

Fetch a single contact by its ID.

GET /v0/contacts/{id}

curl https://api.valise.works/v0/contacts/d2qv9c35i88kat3bkc7g
  --header "Authorization: Bearer <API_KEY>"

The response has the same shape as a single entry in the list contacts endpoint. If the contact isn’t in your vault, the API returns a 404.

Create a contact

Create a new contact in your vault. Requires a key with read and write permission.

POST /v0/contacts

curl https://api.valise.works/v0/contacts
  --method POST
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"name": "Riverside Gallery", "email": "hello@riverside.example"}'

On success, the API returns a 201 status code with the new contact:

{
  "data": {
    "id": "d2qv9c35i88kat3bkc7g",
    "name": "Riverside Gallery",
    "email": "hello@riverside.example",
    "notes": "",
    "createdAt": "2024-09-06T11:17:15.150Z",
    "updatedAt": "2024-09-06T11:17:15.150Z"
  }
}

Update a contact

Change a contact’s details. Only the fields you pass are changed, and the contact keeps its ID, so every work, sale, and consignment that references it keeps pointing to it. Requires a key with read and write permission.

PATCH /v0/contacts/{id}

curl https://api.valise.works/v0/contacts/d2qv9c35i88kat3bkc7g
  --method PATCH
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"email": "gallery@riverside.example"}'

On success, the API returns a 200 status code with the updated contact.

Delete a contact

Permanently delete a contact. Works credited to the contact lose that credit, and sales and consignments that reference it are left without the buyer, seller, or consignee. Those records themselves are not deleted. This cannot be undone. Requires a key with read and write permission.

DELETE /v0/contacts/{id}

curl https://api.valise.works/v0/contacts/d2qv9c35i88kat3bkc7g
  --method DELETE
  --header "Authorization: Bearer <API_KEY>"

On success, the API returns a 204 status code with no response body.

Credit an artist on an artwork

Add an existing contact to the artists credited on an artwork. The contact must already be in your vault, so create it first if it doesn’t exist. Requires a key with read and write permission.

POST /v0/artworks/{id}/artists

curl https://api.valise.works/v0/artworks/d2qv8sj5i88kat3bka30/artists
  --method POST
  --header "Authorization: Bearer <API_KEY>"
  --header "Content-Type: application/json"
  --data '{"contactId": "d2qv9c35i88kat3bkc7g"}'

On success, the API returns a 200 status code with the updated artwork, including its new artistIds. Crediting a contact the artwork already lists also returns 200 and changes nothing, so it’s safe to retry. If the artwork or the contact isn’t in your vault, the API returns a 404.

Remove an artist from an artwork

Remove a contact from the artists credited on an artwork. The contact itself is not deleted. Requires a key with read and write permission.

DELETE /v0/artworks/{id}/artists/{contactId}

curl https://api.valise.works/v0/artworks/d2qv8sj5i88kat3bka30/artists/d2qv9c35i88kat3bkc7g
  --method DELETE
  --header "Authorization: Bearer <API_KEY>"

On success, the API returns a 204 status code with no response body. Removing a contact the artwork doesn’t credit also returns 204.