Capturia measures its ads and site traffic with the Meta pixel and Google Analytics. You can decline at any time. Learn more

Capturia / docs
FR

Tags

2 endpoints

get/v1/tags

List tags

Returns the paginated list of the client's tags (cursor v2). Stable sort name ASC, id ASC — alphabetical order makes it easy to build a selection UI. The id ASC tiebreaker guarantees a total order across pages (names are unique within the account and case-sensitive).

Cursor sanitization

Since name is user-controlled, the cursor encodes values with PostgREST escaping on the server — no action is required on your side.

Required scopes: tags:read

Responses

StatusDescription
200

Paginated list of tags.

400

The request is malformed (missing header, invalid JSON, invalid parameter).

401

Unknown API key or invalid format.

403

Authorization denied. Two causes, distinguished by code: insufficient_scope (the key lacks the required scope — details.required_scope) or feature_not_available (the public API or the targeted module isn't included in the account's plan — details.feature names the feature, e.g. public_api, quotes). A plan denial is final for the key: don't retry; the account must change plans.

429

The per-window request quota has been exceeded for this API key or endpoint.

500

Unexpected server error. Always include the request_id when contacting support.

Example request

curl -X GET 'https://api.capturia.io/v1/tags' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json'
post/v1/tags

Create a tag

Creates a new tag in the client's library. Only name is required — color defaults to #6b7280 (neutral gray) if not provided. To attach the tag to an existing contact, use POST /v1/contacts/{id}/tags with the identifier returned by this endpoint.

The name is unique within the account: a name that is already taken returns 409 duplicate_resource. A name that starts with "Campagne :" (any casing and spacing) is reserved for campaign tags managed by Capturia and returns 400 validation_error, with details: { field: "name", reason: "reserved_prefix" }. A missing name returns 400 validation_error with details: { field: "name", reason: "required" }.

Required scopes: tags:write

Request body

PropertyTypeRequiredDescription
namestringrequiredDisplay name of the tag.
colorstringoptionalHexadecimal color #RRGGBB. Server default: #6b7280.
descriptionstringoptionalFree-form description.
categorystringoptionalGrouping category.

Responses

StatusDescription
201

Tag created.

400

Parameter or body validation failed.

401

Unknown API key or invalid format.

403

Authorization denied. Two causes, distinguished by code: insufficient_scope (the key lacks the required scope — details.required_scope) or feature_not_available (the public API or the targeted module isn't included in the account's plan — details.feature names the feature, e.g. public_api, quotes). A plan denial is final for the key: don't retry; the account must change plans.

409

A resource with a conflicting unique identifier already exists.

415

The Content-Type header is missing or not supported for this endpoint.

429

The per-window request quota has been exceeded for this API key or endpoint.

500

Unexpected server error. Always include the request_id when contacting support.

Example request

curl -X POST 'https://api.capturia.io/v1/tags' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Lead chaud",
  "color": "#ef4444",
  "description": "Prospect avec budget confirmé et calendrier court.",
  "category": "priority"
}'