# 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.com 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

Our documentation is organized into sections that correspond to the main areas of the User.com web application. You can use the navigation menu on the left to select a section and find the endpoint you need.

Each endpoint page includes:

• A short description and usage example.
• An overview of request parameters.
• Code snippets in various languages, including cURL, JavaScript (jQuery & Node.js), PHP, and Python.

# 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 users, the URL would be: https://<your_app_subdomain>.user.com/api/public/users/

This request will display list of all our users.

# Example request

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'

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

$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;

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)

# Response pagination

We use cursor-based pagination and return up to 100 results per page (the exact limit may vary by endpoint) to prevent overload of data and ensure optimal performance.

# Response fields

# Pagination examples

First page (no previous link):

{
  "count": 664,
  "next": "https://<your_app_subdomain>.user.com/api/public/users/?cursor=1971",
  "previous": null,
  "results": [
    // 100 user objects...
  ]
}

Middle page (has both links):

{
  "count": 664,
  "next": "https://<your_app_subdomain>.user.com/api/public/users/?cursor=1525",
  "previous": "https://<your_app_subdomain>.user.com/api/public/users/?cursor=1970&rev=1",
  "results": [
    // 100 user objects...
  ]
}

Last page (no next link, partial results):

{
  "count": 664,
  "next": null,
  "previous": "https://<your_app_subdomain>.user.com/api/public/users/?cursor=1122&rev=1",
  "results": [
    // 64 user objects...
  ]
}

Navigation: Use the complete URLs from next/previous fields. Forward navigation uses ?cursor=VALUE, backward navigation uses ?cursor=VALUE&rev=1.

# Important note about pagination

# Request limits