Skip to content

Update Profile API

The Update Profile API changes an existing profile's name and description with a partial PATCH request. Send only the fields you want to change, use the Profile ID in the path to identify the target, and check the returned profile and status code to confirm the update. This page documents the exact endpoint, parameters, example request, response shape, and failure cases for that operation.

Update Profile API

Use the Update Profile API when you need to rename a profile or replace its description without recreating the profile. The operation is a partial update: every body field is optional, so you include only the values that should change and leave the rest out. That distinction matters for description in particular. Omitting description leaves the existing value unchanged, while sending description as null clears it. Before sending a request, confirm the Profile ID you intend to target, prepare a name between 1 and 200 characters if you are changing it, and keep any new description at or below 1000 characters. After the request, compare the returned profile fields with what you sent, check that updatedAt reflects the change, and treat a 400 or 404 response as a failure to correct rather than as a successful update.

Endpoint

Send a PATCH request to the endpoint shown in the Endpoint table below, with the Profile ID substituted for the id placeholder in the path. Include the x-access-key header with your API key and set Content-Type to application/json, as shown in the cURL example titled Update Profile API cURL example. The path parameter is required and is the only identifier for the profile being updated, so a malformed or unknown value can lead to an invalid profile id or a not found result depending on how the request is processed.

Path Parameters

The path contains one required parameter, id, typed as a string and described as the Profile ID. Place the identifier directly in the /v1/profiles/{id} path segment. Do not move this identifier into the JSON body, because the documented contract expects it in the path while name and description belong in the body.

Body Parameters

All body fields are optional, and you should pass only the ones you want to change. The name field is a string for the new name and must be between 1 and 200 characters when supplied. The description field is a string or null, with a maximum of 1000 characters when supplied as a string, and passing null clears the existing description. Use that null value deliberately: it is the documented way to clear a description, whereas omitting the field preserves the current description. If a request fails with an invalid body error, check the types and lengths of the fields you sent, confirm that description is either a string within the limit or null, and confirm that you did not rely on any field outside the documented name and description contract.

Example

The worked example titled Update Profile API cURL example sends a PATCH request for profile 65ab123 with a new name and description. Adapt the identifier, API key placeholder, and JSON values to your own profile, then inspect the response before treating the change as complete. A useful failure check is to send one field at a time during development: first confirm that a name-only update leaves the description unchanged, then confirm that an explicit null description clears it, so the two behaviors are not confused in your client code.

Response

A successful response returns success set to true and a profile object containing id, name, description, integrationCount, createdAt, and updatedAt. The integrationCount field reports the count of active integrations bound to the profile at the time of the response. Use the returned profile as the source of truth for the stored values after the update, rather than assuming the request body was applied exactly as intended, and check updatedAt to confirm the profile record changed.

Status Codes

Interpret the status code together with the response body. A 200 response means Profile updated and should include the updated profile. A 400 response means Invalid profile id or invalid body, so recheck the Profile ID in the path and the types, lengths, and null handling of the JSON body. A 404 response means Profile not found, so verify that the identifier refers to an existing profile before retrying the same request. Keeping these three outcomes separate in your error handling prevents a missing profile from being reported as a malformed request, and vice versa.

Endpoint
MethodEndpoint
PATCH{{API_BASE_URL}}/v1/profiles/{id}

Origin-modular parity contract; {{API_BASE_URL}} replaces only the origin.

Path Parameters
ParameterTypeDescription
idstringProfile ID

Required path parameter.

Body Parameters
ParameterTypeRequiredDescription
namestringOptionalNew name (1–200 chars).
descriptionstring | nullOptionalNew description (max 1000 chars). Pass null to clear.

All fields are optional; pass only the ones you want to change.

Status Codes
CodeMeaningWhat to check
200Profile updatedConfirm the returned profile fields and updatedAt.
400Invalid profile id or invalid bodyRecheck the Profile ID, field types, name length, and description length or null value.
404Profile not foundVerify the Profile ID refers to an existing profile.

Documented status contract for this operation.

Update Profile API cURL example
curl -X PATCH "{{API_BASE_URL}}/v1/profiles/65ab123" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Inc", "description": "Example post details." }'
Update Profile API response example
{
	"success": true,
	"profile": {
		"id": "65ab...",
		"name": "Acme Inc",
		"description": "Example post details.",
		"integrationCount": 3,
		"createdAt": "2026-05-03T08:33:36.445Z",
		"updatedAt": "2026-05-03T09:01:11.000Z"
	}
}
Contract example 1
PATCH {{API_BASE_URL}}/v1/profiles/{id}