Update Association

This endpoint updates the contact role or notification level of an existing project-to-contact association. You identify the association by the project ID in the path and the contact ID in the body or query string.

Endpoint

PUT /v1/associations/associations/:id

Authentication

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

Required Scope

associations:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID.

Query Parameters

Parameter	Type	Required	Description
contactId	string	No	Contact ID. Use this or contactId in the body.

Request Body

You must send a JSON body with Content-Type: application/json, even when you pass contactId in the query string. Send at least {}. A request with no body returns 500.

Field	Type	Required	Description
contactId	string	No	Contact ID. Required here if it is not in the query string. If it is in both places, the values must match.
projectId	string	No	If provided, it must match the route id.
contactType	"MANAGER" | "BACKUP_MANAGER" | "ADDITIONAL_CONTACT"	No	New contact role.
notificationLevel	"NONE" | "COPY_ONLY" | "COPY_WITH_LINK"	No	New notification level.

The API does not check contactType and notificationLevel against the allowed values. Other strings are stored as sent, so send only the values listed above.

Example Request Body

{
  "contactId": "contact-jkl123mno4567890",
  "notificationLevel": "COPY_WITH_LINK"
}

Example Request

cURL

curl -X PUT "https://api.crewsum.com/v1/associations/associations/project-mno123pqr4567890" \
  -H "x-api-key: $CREWSUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "contact-jkl123mno4567890",
    "notificationLevel": "COPY_WITH_LINK"
  }'

JavaScript

const response = await fetch(
  "https://api.crewsum.com/v1/associations/associations/project-mno123pqr4567890",
  {
    method: "PUT",
    headers: {
      "x-api-key": process.env.CREWSUM_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contactId: "contact-jkl123mno4567890",
      notificationLevel: "COPY_WITH_LINK",
    }),
  },
);
const result = await response.json();

HTTP

PUT /v1/associations/associations/project-mno123pqr4567890 HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>
Content-Type: application/json

{
  "contactId": "contact-jkl123mno4567890",
  "notificationLevel": "COPY_WITH_LINK"
}

Response

On success, the API returns HTTP 200 OK.

Example Response

{
  "message": "Successfully updated association"
}

Behavior

• Only contactType and notificationLevel can change. To associate a different project or contact, delete this association and create a new one.
• Changing notificationLevel to COPY_WITH_LINK with this endpoint does not run the outstanding-timecard check that Create Association runs.
• If your account has no association for the project and contact, the API returns 404 and changes nothing.
• After the association is updated, Crewsum emits the associations.updated webhook event. A webhook delivery failure does not change the API response.

Error Responses

Status	Meaning
400	contactId must be supplied: contactId was not in the body or the query string.
400	projectId in request body must match the route id.
400	contactId in request body must match the query string.
400	The request had Content-Type: application/json and an empty body. Send at least {}.
404	Your account has no association for the project and contact. The message is Association between <projectId> and <contactId> not found.
500	The request had no JSON body.
500	Crewsum could not update the association. The message is Error updating association.

Authentication and scope failures are described in Errors.

Related Webhooks

associations.updated View webhook event details.