Reference

Tags

Tags are user-scoped labels attachable to contacts. Each tag has a name and an optional hex color. Tag deletion against an in-use tag returns 409 unless force=true is sent.

List tags

Returns all tags owned by the authenticated user, sorted alphabetically. Each tag includes the count of associated contacts.

GET /api/tags

curl --request GET \
    --get "https://klozzo.com/api/tags" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://klozzo.com/api/tags"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://klozzo.com/api/tags';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://klozzo.com/api/tags'
headers = {
  'Authorization': 'Bearer {YOUR_API_TOKEN}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

{
    "data": [
        {
            "id": null,
            "name": "aut",
            "slug": null,
            "color": "#a11e59",
            "location_id": null,
            "created_at": null,
            "updated_at": null
        },
        {
            "id": null,
            "name": "modi",
            "slug": null,
            "color": "#865450",
            "location_id": null,
            "created_at": null,
            "updated_at": null
        }
    ]
}

data object[]
- id string
- name string
- slug string
- color string
- location_id string
- created_at string
- updated_at string

Tags are the free-form way to group people: a campaign, an event, a list you built by hand. Use them for something you will want to filter by later but that has no value of its own — when the thing you want to record has a value ("budget", "plan", "renewal date"), a custom field is what you want instead.

POST /api/tags

The name is unique inside the location; creating one that already exists answers 422 rather than a second tag with the same name.

Body parameters

name string required

Tag name (max 255).

Example: VIP
color string

Hex color including the # prefix.

Example: #ff6b35

curl --request POST \
    "https://klozzo.com/api/tags" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"VIP\",
    \"color\": \"#ff6b35\"
}"

const url = new URL(
    "https://klozzo.com/api/tags"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "VIP",
    "color": "#ff6b35"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://klozzo.com/api/tags';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'VIP',
            'color' => '#ff6b35',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://klozzo.com/api/tags'
payload = {
    "name": "VIP",
    "color": "#ff6b35"
}
headers = {
  'Authorization': 'Bearer {YOUR_API_TOKEN}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

{
    "data": {
        "id": null,
        "name": "nihil",
        "slug": null,
        "color": "#c8a15d",
        "location_id": null,
        "created_at": null,
        "updated_at": null
    }
}

data object
- id string
- name string
- slug string
- color string
- location_id string
- created_at string
- updated_at string

{
    "message": "Color no tiene un formato válido.",
    "errors": {
        "color": [
            "Color no tiene un formato válido."
        ]
    }
}

Every error shares the same shape — message and errors. See Errors.

{
    "message": "El valor de name ya está en uso.",
    "errors": {
        "name": [
            "El valor de name ya está en uso."
        ]
    }
}

Every error shares the same shape — message and errors. See Errors.

Fetch a tag

Returns one tag by id, with how many contacts carry it. Useful before deleting one: the count is what tells you whether removing it is housekeeping or data loss.

GET /api/tags/{id}

Path parameters

id integer required

Tag ID.

Example: 3

curl --request GET \
    --get "https://klozzo.com/api/tags/3" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://klozzo.com/api/tags/3"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://klozzo.com/api/tags/3';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://klozzo.com/api/tags/3'
headers = {
  'Authorization': 'Bearer {YOUR_API_TOKEN}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()

{
    "data": {
        "id": null,
        "name": "adipisci",
        "slug": null,
        "color": "#f76df4",
        "location_id": null,
        "created_at": null,
        "updated_at": null
    }
}

data object
- id string
- name string
- slug string
- color string
- location_id string
- created_at string
- updated_at string

{
    "message": "No query results for model."
}

Every error shares the same shape — message and errors. See Errors.

Update a tag

Updates a tag's name or colour by id. Every contact carrying the tag sees the new name immediately — a tag is one row, not a copy per contact — so renaming is how you fix a typo, never how you split a group in two.

PUT /api/tags/{id}

Path parameters

id integer required

Tag ID.

Example: 3

Body parameters

name string

Tag name (max 255).

Example: VIP Customer
color string

Hex color including the # prefix.

Example: #ff6b35

curl --request PUT \
    "https://klozzo.com/api/tags/3" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"VIP Customer\",
    \"color\": \"#ff6b35\"
}"

const url = new URL(
    "https://klozzo.com/api/tags/3"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "VIP Customer",
    "color": "#ff6b35"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://klozzo.com/api/tags/3';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'VIP Customer',
            'color' => '#ff6b35',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://klozzo.com/api/tags/3'
payload = {
    "name": "VIP Customer",
    "color": "#ff6b35"
}
headers = {
  'Authorization': 'Bearer {YOUR_API_TOKEN}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('PUT', url, headers=headers, json=payload)
response.json()

{
    "data": {
        "id": null,
        "name": "accusantium",
        "slug": null,
        "color": "#902510",
        "location_id": null,
        "created_at": null,
        "updated_at": null
    }
}

data object
- id string
- name string
- slug string
- color string
- location_id string
- created_at string
- updated_at string

Delete a tag

Deletes a tag by id. If the tag is attached to any contacts, returns 409 unless force=true is passed, in which case the tag is detached from all contacts then deleted.

DELETE /api/tags/{id}

Path parameters

id integer required

Tag ID.

Example: 3

Query parameters

force boolean

Detach from contacts and delete anyway.

Example: true

curl --request DELETE \
    "https://klozzo.com/api/tags/3?force=1" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://klozzo.com/api/tags/3"
);

const params = {
    "force": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://klozzo.com/api/tags/3';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'force' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://klozzo.com/api/tags/3'
params = {
  'force': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_TOKEN}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('DELETE', url, headers=headers, params=params)
response.json()

{
    "message": "Tag deleted."
}

message string

{
    "message": "Tag is in use.",
    "contacts_count": 12,
    "hint": "Pass force=true to detach and delete."
}

Every error shares the same shape — message and errors. See Errors.

List tags

Create a tag

Body parameters

Fetch a tag

Path parameters

Update a tag

Path parameters

Body parameters

Delete a tag

Path parameters

Query parameters