All endpoints use HTTPS. HTTP requests are not supported.
***
The ParsaLink API uses Bearer token authentication. Include your access token in the `Authorization` header of every request:
```http theme={null}
Authorization: Bearer
```
### Obtaining a Token
Authenticate by calling the login endpoint with your email and password:
```http theme={null}
POST https://api.parsalink.io/api/auth/login/
Content-Type: application/json
{
"email": "you@example.com",
"password": "your_password"
}
```
**Response:**
```json theme={null}
{
"access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "usr_01HX...",
"email": "you@example.com",
"firstName": "Jane",
"lastName": "Smith"
}
}
```
The `access` token is valid for **1 hour**. Use the `refresh` token to get a new access token without re-entering credentials.
See [Authentication](/api-reference/authentication) for full details on token refresh and API key authentication.
***
Responses
## Response Format
All responses are JSON. Field names use **camelCase** throughout the API.
### Success Response
```json theme={null}
{
"id": "cnt_01HX...",
"firstName": "John",
"lastName": "Smith",
"email": "john@acme.com",
"stage": "engaged",
"createdAt": "2025-03-15T10:30:00Z",
"updatedAt": "2025-03-20T14:22:00Z"
}
```
### Paginated List Response
```json theme={null}
{
"count": 142,
"next": "https://api.parsalink.io/api/contacts/?page=2",
"previous": null,
"results": [...]
}
```
Use the `next` URL directly to fetch the next page. You can also pass `?page=N` or `?limit=N&offset=N` query parameters.
***
Errors
## Error Handling
Errors return standard HTTP status codes with a JSON body explaining the error.
| Status Code | Meaning |
| ----------- | ------------------------------------------------------------------ |
| `400` | Bad Request — invalid or missing parameters |
| `401` | Unauthorized — missing or invalid token |
| `403` | Forbidden — authenticated but not permitted to perform this action |
| `404` | Not Found — resource doesn't exist or isn't accessible to you |
| `422` | Unprocessable Entity — validation error |
| `429` | Too Many Requests — rate limit exceeded |
| `500` | Internal Server Error — something went wrong on our end |
**Error response body:**
```json theme={null}
{
"detail": "Authentication credentials were not provided."
}
```
For validation errors:
```json theme={null}
{
"email": ["This field is required."],
"stage": ["Value 'invalid_stage' is not a valid choice."]
}
```
***
Rate Limits
## Rate Limiting
Each plan has a defined request rate limit.
| Plan | Rate Limit |
| ---------- | ------------------- |
| Starter | 100 requests/minute |
| Growth | 300 requests/minute |
| Business | 600 requests/minute |
| Enterprise | Custom |
Rate limit headers are returned with every response:
```http theme={null}
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1711500060
```
When you exceed the limit, a `429` response is returned. The `X-RateLimit-Reset` value is a Unix timestamp indicating when the rate limit window resets.
***
Versioning
## Versioning
The current API version is **v1**, which is the default when no version is specified. Breaking changes will be introduced with a new version prefix (e.g., `/api/v2/`). The current version will be supported for at least 12 months after a new version is released.