Basic API usage

This guide provides a brief introduction to our API, including how to make simple requests and understand example responses.

---

Welcome to the User API! This tutorial will help you understand the basics of using our API to retrieve data and build integrations with our application.

An API (Application Programming Interface) is an interface that allows different software components to communicate. Our API follows REST (Representational State Transfer) principles, which means you can perform actions using standard HTTP methods like POST, PUT, GET, and DELETE.

Navigating the documentation

Every endpoint is described in the API Reference, grouped by the area of the User app it belongs to (contacts, deals, products and so on). Pick a group in the menu on the left to find the endpoint you need.

Each endpoint page includes:

• A short description of what the endpoint does.
• The request parameters.
• A request example in cURL, JavaScript, PHP and Python.
• Response examples and a description of the response fields.

API endpoint structure

All API requests should be made to the following base URL, ensuring it ends with a trailing slash: https://<your_app_subdomain>.user.com/api/public/

The rest of the URL path depends on the specific resource you want to access. For example, to access contacts, the URL would be: https://<your_app_subdomain>.user.com/api/public/users/

REQUIRED HEADERS

Every API request must include the following headers:

• Authorization: Token <your_64_char_api_key> — Your API key for authentication
• Accept: */*; version=2 — Specifies API version 2 (current version)

Omitting the Accept header or using a different version value will result in unexpected behavior or errors.

Example request

This request returns one contact by its ID. Replace :id with the contact's id.

cURL

curl --location --request GET 'https://<your_app_subdomain>.user.com/api/public/users/:id/' \
--header 'Authorization: Token <your_64_char_api_key>' \
--header 'Accept: */*; version=2'

JavaScript

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://<your_app_subdomain>.user.com/api/public/users/:id/");
xhr.setRequestHeader("Authorization", "Token <your_64_char_api_key>");
xhr.setRequestHeader("Accept", "*/*; version=2");

xhr.send();

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<your_app_subdomain>.user.com/api/public/users/:id/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Token <your_64_char_api_key>',
    'Accept: */*; version=2'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python

import requests

url = "https://<your_app_subdomain>.user.com/api/public/users/:id/"

payload={}
headers = {
  'Authorization': 'Token <your_64_char_api_key>',
  'Accept': '*/*; version=2'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Lists and pagination

Endpoints that return many records return them one page at a time. See Pagination for how to get the next page.

Request limits

API requests are limited to 10 requests per second per workspace, shared by all its API keys. Requests over the limit get 429 Too Many Requests. See Rate limits for how to stay within the limit and handle 429.