# Basic API usage

Briefly described how to use our API, simple request & example response.


Welcome to User.com basic API overview. This tutorial will help you learn and understand the basics of using User.com API to get the data you need and develop integration with our application. An API is an application programming interface - in short, it's a computing interface to another software component. REST stands for Representational State Transfer. You can perform many different methods (POST, PUT, GET, DELETE) over HTTP. Our docs are divided into sections responding to the Web application panel. From the dropdown menu on the left, you can choose an interesting section and then search for the desired endpoint. Every page starts with a short description/usage example. Then we move to the request parameters overview. After that, you can find snippet codes for programming languages like:

  • jQuery, Javascript, Node.js, PHP and Python. Also, we include a simple snippet for curl requests. Every request begins with https://<your_app_subdomain>.user.com/api/public/ Every request ends with following trailing slash. Like the example URL above. The next part of the URI depends on the type of request. For example: https://<your_app_subdomain>.user.com/api/public/users/

INFO

Each and every request must have Authorization: Token <your_64_char_api_key> included in header.

This request will display list of all our users.

# Example request

curl -X GET -H "Authorization: Token <your_64_char_api_key>"
-H "Accept: */*; version=2"
"https://<your_app_subdomain>.user.com/api/public/users/:id/"

# 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

Field Type Description
count integer Total number of items across all pages
next string/null URL for the next page (null on last page)
previous string/null URL for the previous page (null on first page)
results array Array of objects for the current page

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

# Request limits

RATE LIMITS

API requests are limited to 10 requests per second per user. Exceeding this limit will result in HTTP 429 (Too Many Requests) responses.