Create Contact

This endpoint creates a contact and returns the generated contact ID.

Endpoint

POST /v1/contacts/contacts

Authentication

Include your API key in the x-api-key header. See Authentication.

Required Scope

contacts:write

Request Body

The server validates the request body. A body that fails validation returns 400 with {"message": "Error parsing body"}. Unknown fields are ignored.

Field	Type	Required	Description
type	"EXTERNAL" | "INTERNAL"	No	Contact record type. Defaults to "EXTERNAL".
name	string	External only	Contact name. Must not be blank for external contacts. Ignored for internal contacts, which use the linked user’s full name.
email	string	External only	Contact email address. Must not be blank for external contacts. Leading and trailing spaces are removed. Ignored for internal contacts, which return the linked user’s email.
userId	string | null	Internal only	ID of the user to link. Accepts the user ID (for example user-a) or the internal <tenantId>#<userId> form. The user must belong to your account. Ignored for external contacts.
clientId	string | null	No	Client to assign the contact to. Omit it or send null to create the contact without a client. A client that does not exist in your account, or is deleted, returns 400.
description	string | null	No	Contact description. Defaults to null.
isArchived	boolean	No	Creates the contact in an archived state when true. Defaults to false.

Example Request Body

External contact:

{
  "type": "EXTERNAL",
  "clientId": "client-ghi123jkl4567890",
  "name": "Contact Name",
  "email": "placeholder@example.com",
  "description": "A brief description of the contact",
  "isArchived": false
}

Internal contact:

{
  "type": "INTERNAL",
  "userId": "user-a",
  "description": "Internal project reviewer"
}

Example Request

cURL

curl -X POST "https://api.crewsum.com/v1/contacts/contacts" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "EXTERNAL",
    "clientId": "client-ghi123jkl4567890",
    "name": "Contact Name",
    "email": "placeholder@example.com",
    "description": "A brief description of the contact",
    "isArchived": false
  }'

JavaScript

const response = await fetch("https://api.crewsum.com/v1/contacts/contacts", {
  method: "POST",
  headers: {
    "x-api-key": process.env.CREWSUM_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "EXTERNAL",
    clientId: "client-ghi123jkl4567890",
    name: "Contact Name",
    email: "placeholder@example.com",
    description: "A brief description of the contact",
    isArchived: false,
  }),
});
const result = await response.json();

HTTP

POST /v1/contacts/contacts HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>
Content-Type: application/json

{
  "type": "EXTERNAL",
  "clientId": "client-ghi123jkl4567890",
  "name": "Contact Name",
  "email": "placeholder@example.com",
  "description": "A brief description of the contact",
  "isArchived": false
}

Response

On success, the API returns HTTP 201 Created.

Example Response

{
  "message": "Successfully created contact: contact-jkl123mno4567890",
  "data": {
    "contactId": "contact-jkl123mno4567890"
  }
}

Behavior

• The API generates the contact ID in the format contact-<16 hex characters>.
• External contacts store their name and email on the contact record.
• Internal contacts link to a user in your account. The contact takes its name from the user’s full name, and responses return the user’s email. Responses return userId in the internal <tenantId>#<userId> form, for example acme#user-a.
• If clientId is set, the client must exist in your account and must not be deleted. Otherwise the API returns 400 with Client not found and creates nothing. Contacts created without a client return null for the client fields.
• The contact is created with portal access turned off (hasPortalAccess: false). Use Update Contact to turn it on.
• After the contact is created, Crewsum attempts to send the project-contacts.created webhook event. A webhook failure does not change the response.

Error Responses

Status	Meaning
400	{"message": "Error parsing body"}. The body failed validation: type is not "EXTERNAL" or "INTERNAL", a field has the wrong type, an external contact has a blank name or email, or an internal contact has no userId. The response does not say which field failed.
400	{"message": "Internal contact user must belong to the current tenant"}. No user with this userId exists in your account.
400	{"message": "Client not found"}. No client with this clientId exists in your account, or the client is deleted. Nothing is created.
500	{"message": "Error creating contact"}. Crewsum could not create the contact.

Authentication and scope failures are described in Errors.

Related Webhooks

project-contacts.created View webhook event details.