API Overview

The Leypal REST API lets you integrate electronic signatures and identity verification into your own systems. This page covers the foundational knowledge you need before making your first request: where to send requests, how to authenticate, what limits apply, and how to interpret responses.

Base URL

All API requests go to a single production endpoint:

https://api.leypal.dev

There is no separate staging or sandbox URL. Use API keys scoped to a test organization for development and QA.
All requests must use HTTPS. Plain HTTP is rejected.
All endpoints are versioned under /api/v1.

Full example:

https://api.leypal.dev/api/v1/signatures

Authentication

Every request requires an API key passed as a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Example

curl https://api.leypal.dev/api/v1/signatures \
  -H "Authorization: Bearer YOUR_API_KEY"

Key Facts

API keys are scoped to an organization. Each request is authenticated as that organization.
Keys have no built-in expiration but can be revoked at any time from the dashboard.
Never expose your API key in client-side code or public repositories.

For key creation, rotation, and revocation steps, see Generating API Keys.

Rate Limiting

Tier	Limit
Free	100 requests / minute per API key
Enterprise	Custom — contact sales

When a request exceeds the limit, the API returns HTTP 429 Too Many Requests.

Rate Limit Headers

Every response includes these headers so you can track consumption:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining before the limit resets
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets

Handling 429 Responses

Read X-RateLimit-Reset and wait until that timestamp before retrying. For bulk operations, implement exponential backoff with jitter to avoid thundering-herd retries.

HTTP Status Codes

Code	Name	When It Occurs
`200`	OK	Request succeeded; response body contains the result
`201`	Created	Resource created successfully; response body contains the new resource
`204`	No Content	Request succeeded; no response body (e.g., DELETE operations)
`400`	Bad Request	Invalid or missing request parameters; fix the request before retrying
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Authenticated, but not authorized to access this resource
`404`	Not Found	The requested resource does not exist
`429`	Too Many Requests	Rate limit exceeded; wait for `X-RateLimit-Reset` before retrying
`500`	Internal Server Error	Unexpected server error; safe to retry with exponential backoff

Check the HTTP status code first. Use the error field in the response body for programmatic branching.

Error Response Format

All error responses return JSON with a consistent structure:

{
  "statusCode": 400,
  "message": "Invalid signer email",
  "error": "ValidationError"
}

Field	Type	Description
`statusCode`	number	HTTP status code (mirrors the response status)
`message`	string	Human-readable description of the error
`error`	string	Machine-readable error type for programmatic handling

Common Error Types

`error` Value	Meaning
`ValidationError`	Request payload failed validation
`UnauthorizedException`	API key missing or invalid
`ForbiddenException`	Insufficient permissions
`NotFoundException`	Resource not found
`TooManyRequestsException`	Rate limit exceeded

SDK Recommendations

Official SDKs are on the roadmap but not yet released.

In the meantime, use your language's native HTTP client:

Language	Recommended Client
JavaScript / TypeScript	`fetch` (native) or `axios`
Python	`requests` or `httpx`
PHP	`GuzzleHttp`
Ruby	`net/http` or `faraday`
Go	`net/http` (standard library)
Java / Kotlin	`OkHttp` or `Retrofit`

All code examples in this documentation use curl for clarity. Translating to any HTTP client is straightforward.

API Endpoints by Feature

Feature	What You Can Do	Reference
Electronic Signatures	Create signature requests, add signers, send for signing, track status, cancel	Electronic Signature Endpoints
Identity Verification	Initiate verification sessions, poll status, retrieve results and evidence	Identity Verification Endpoints
API Keys	Generate, list, and revoke organization API keys	API Authentication

Next Steps

Electronic Signature Endpoints — Full reference for creating and managing signature requests
Identity Verification Endpoints — Full reference for identity verification sessions
Quick Start Guide — Step-by-step: API key → first signature request

API Overview

On this page