# Books & Labels
Retrieve your team's books and their labels, and manage label assignments on contacts.
---
## List Books
Retrieve all books that belong to your team. Each book includes a `contact_count` showing how many contacts it contains.
```
GET /api/v1/books
```
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | `Bearer rlb_your_key` |
> [!note] No X-Book-ID needed
> This endpoint returns all team books, so the `X-Book-ID` header is not required.
### Example Request
```bash
curl -X GET "https://app.relaybook.io/api/v1/books" \
-H "Authorization: Bearer rlb_your_key"
```
### Response
```
HTTP/1.1 200 OK
```
```json
{
"data": [
{
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"name": "Sales Leads",
"slug": "sales-leads",
"color": "#4A9EE5",
"icon": "briefcase",
"contact_count": 47
},
{
"id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
"name": "Vendors",
"slug": "vendors",
"color": "#10B981",
"icon": "building",
"contact_count": 12
}
]
}
```
### Errors
| Status | Code | Cause |
|--------|------|-------|
| 500 | `SERVER_ERROR` | Database error |
---
## Get Book
Retrieve a single book by its ID.
```
GET /api/v1/books/{id}
```
### Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | The book's unique ID |
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | `Bearer rlb_your_key` |
### Example Request
```bash
curl -X GET "https://app.relaybook.io/api/v1/books/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
-H "Authorization: Bearer rlb_your_key"
```
### Response
```
HTTP/1.1 200 OK
```
```json
{
"data": {
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"name": "Sales Leads",
"slug": "sales-leads",
"color": "#4A9EE5",
"icon": "briefcase",
"contact_count": 47
}
}
```
### Errors
| Status | Code | Cause |
|--------|------|-------|
| 404 | `NOT_FOUND` | Book doesn't exist or doesn't belong to your team |
---
## Book Object
| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Unique book identifier |
| `name` | string | Display name of the book |
| `slug` | string | URL-safe version of the name |
| `color` | string | Hex color code (e.g. `#4A9EE5`) |
| `icon` | string | Icon identifier |
| `contact_count` | integer | Number of contacts in the book |
---
## List Labels
Retrieve all labels for a specific book. Labels are color-coded tags used to categorize contacts.
```
GET /api/v1/books/{id}/labels
```
### Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | The book's unique ID |
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | `Bearer rlb_your_key` |
### Example Request
```bash
curl -X GET "https://app.relaybook.io/api/v1/books/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/labels" \
-H "Authorization: Bearer rlb_your_key"
```
### Response
```
HTTP/1.1 200 OK
```
```json
{
"data": [
{
"id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
"name": "Hot Lead",
"color": "#EF4444",
"sort_order": 0
},
{
"id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
"name": "Partner",
"color": "#10B981",
"sort_order": 1
},
{
"id": "e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b",
"name": "Vendor",
"color": "#8B5CF6",
"sort_order": 2
}
]
}
```
### Errors
| Status | Code | Cause |
|--------|------|-------|
| 403 | `FORBIDDEN` | Book doesn't belong to your team |
| 500 | `SERVER_ERROR` | Database error |
---
## Add Label to Contact
Assign a label to a contact. The label must belong to the same book as the contact.
```
POST /api/v1/contacts/{id}/labels
```
### Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | The contact's unique ID |
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | `Bearer rlb_your_key` |
| `Content-Type` | Yes | `application/json` |
### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label_id` | UUID | Yes | ID of the label to add |
### Example Request
```bash
curl -X POST "https://app.relaybook.io/api/v1/contacts/f47ac10b-58cc-4372-a567-0e02b2c3d479/labels" \
-H "Authorization: Bearer rlb_your_key" \
-H "Content-Type: application/json" \
-d '{
"label_id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f"
}'
```
### Response
```
HTTP/1.1 200 OK
```
```json
{
"data": {
"message": "Label added"
}
}
```
> [!note] Duplicate labels are ignored
> If the contact already has the label, the request succeeds silently without creating a duplicate.
### Errors
| Status | Code | Cause |
|--------|------|-------|
| 400 | `INVALID_INPUT` | `label_id` is missing or the label doesn't belong to the same book as the contact |
| 404 | `NOT_FOUND` | Contact doesn't exist or doesn't belong to your team |
| 500 | `SERVER_ERROR` | Database error |
---
## Remove Label from Contact
Remove a label from a contact.
```
DELETE /api/v1/contacts/{id}/labels/{lid}
```
### Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | The contact's unique ID |
| `lid` | UUID | The label's unique ID |
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | `Bearer rlb_your_key` |
### Example Request
```bash
curl -X DELETE "https://app.relaybook.io/api/v1/contacts/f47ac10b-58cc-4372-a567-0e02b2c3d479/labels/c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f" \
-H "Authorization: Bearer rlb_your_key"
```
### Response
```
HTTP/1.1 204 No Content
```
No response body is returned.
> [!note] Removing a non-existent label
> If the contact doesn't have the specified label, the request succeeds silently.
### Errors
| Status | Code | Cause |
|--------|------|-------|
| 404 | `NOT_FOUND` | Contact doesn't exist or doesn't belong to your team |
| 500 | `SERVER_ERROR` | Database error |
---
## Label Object
| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Unique label identifier |
| `name` | string | Display name of the label |
| `color` | string | Hex color code (e.g. `#EF4444`) |
| `sort_order` | integer | Position in the label list |
---
**Next:** Set up real-time notifications with [[Webhooks]].