> ## Documentation Index > Fetch the complete documentation index at: https://doc.youverify.co/llms.txt > Use this file to discover all available pages before exploring further. # Youverify REST API Reference — Overview & Conventions > Base URLs, request format, authentication, response envelope, error codes, pagination, and rate limits for the Youverify REST API. The Youverify REST API gives you programmatic access to the full FRAML platform: create and monitor entities, run KYC, KYB, and AML checks, ingest transactions for KYT, manage cases, and stream signals — all over JSON and HTTPS. Every resource in this reference follows the same conventions, so once you understand the envelope and authentication pattern, the rest is consistent throughout. ## Base URLs Youverify provides two fully isolated environments. Use the sandbox for integration and testing; switch to production when you are ready for live, billed checks. | Environment | Base URL | Purpose | | - | - | - | | **Sandbox** | `https://api.sandbox.youverify.co` | Integration & testing — test data, not billed | | **Production** | `https://api.youverify.co` | Real checks against authoritative sources, billed | Never mix credentials between environments. A sandbox key will be rejected by the production endpoint, and vice versa. ## Request Format All requests and responses are JSON over HTTPS. Set the following headers on every call: ```http theme={null} token: YOUR_SECRET_KEY Content-Type: application/json ``` ## Authentication Youverify authenticates server-to-server calls with a single `token` header. There is no OAuth handshake — possession of the secret key is authority, so it must **never** leave your backend. See the [Authentication reference](/api-reference/authentication) for full details, key types, and security best practices. ## Response Envelope Every successful response shares the same shape, so you write your deserialization logic once: ```json theme={null} { "success": true, "status_code": 200, "message": "Human-readable outcome.", "data": {}, "links": [] } ``` `true` on all successful responses. HTTP status code mirrored in the body, e.g. `200`, `201`. A human-readable description of the outcome. The primary payload — an object for single-resource endpoints, an array for list endpoints. Hypermedia links for navigation (pagination cursors, related resources). ## Error Envelope When a request fails, the response uses the same skeleton with `success: false` and a machine-readable error `name`: ```json theme={null} { "success": false, "statusCode": 404, "name": "ResourceNotFoundError", "message": "Entity with ID ent_abc123 was not found." } ``` Always `false` for error responses. The HTTP status code for the error. A machine-readable error identifier, e.g. `ResourceNotFoundError`, `ValidationError`, `UnauthorizedError`. A human-readable explanation of what went wrong. ### Common HTTP Status Codes | Code | Meaning | | - | - | | `200 OK` | Request succeeded | | `201 Created` | Resource was created successfully | | `400 Bad Request` | Invalid request body or missing required parameter | | `401 Unauthorized` | Missing or invalid `token` header | | `403 Forbidden` | Valid token but insufficient plan or permission | | `404 Not Found` | The requested resource does not exist | | `422 Unprocessable Entity` | Request is well-formed but semantically invalid | | `429 Too Many Requests` | Rate limit exceeded — retry after the `Retry-After` header | | `500 Internal Server Error` | Unexpected server error | ## Pagination ### Offset Pagination Most list endpoints support offset-based pagination via `page` and `limit` query parameters: ```http theme={null} GET /v2/api/entities?page=2&limit=50 ``` The page number to retrieve. Number of results per page. Maximum is `100`. The paginated response includes metadata alongside the `data` array: ```json theme={null} { "success": true, "status_code": 200, "message": "Entities retrieved successfully.", "data": { "total": 342, "page": 2, "limit": 50, "list": [] }, "links": [] } ``` ### Cursor Pagination High-volume streams such as Signals support cursor-based pagination, which is preferred for production polling because it handles real-time data without skipping or duplicating records. Pass the `cursor` value returned in `links` as a query parameter on the next request. ## Entity IDs All entities carry a stable, globally unique identifier prefixed with `ent_`: ``` ent_685c73c8519d82bd21a42fae ``` This ID is permanent for the lifetime of the entity. Reference it across KYC, KYB, AML, KYT, and case management calls so every result attaches to the entity's 360 record rather than existing as an orphaned report. ## Rate Limits Youverify enforces per-workspace rate limits. When you exceed them, the API returns `429 Too Many Requests` with a `Retry-After` header indicating how many seconds to wait before retrying: ```http theme={null} HTTP/1.1 429 Too Many Requests Retry-After: 30 ``` Implement exponential backoff with jitter in your retry logic to avoid thundering-herd problems when operating near your rate limit. ## Resource Groups The API is organized around the following resource groups: Create, retrieve, and manage individual and business entities. The central object everything else references. Run identity checks against government ID databases — BVN, NIN, passport, driver's license, and more. Verify businesses against company registries. Retrieve registration details, directors, shareholders, and UBOs. Screen entities against PEP lists, global sanctions databases, and adverse media sources. Ingest transactions and receive real-time risk evaluations and fraud signals for transaction monitoring. Open, update, and close investigation cases linked to entities. The human-in-the-loop layer. Retrieve detected events, patterns, and alerts generated by fraud traps and monitoring rules. Access risk scores, scoring breakdowns, and risk model configuration for your workspace.