# 03 api reference

\# API Reference

\> Complete reference for the LeadSonar REST API. All endpoints require authentication via API key.

\## POST /api/v1/find-email

Find a verified work email for a person.

\*\*Request body\*\*

\| Field | Type | Required | Description | |-------|------|----------|-------------| | firstName | string | Yes | Contact's first name | | lastName | string | Yes | Contact's last name | | company | string | No | Company name | | website | string | No | Company domain (e.g. \`stripe.com\`) |

Provide at least \`company\` or \`website\` alongside the name.

\*\*Example\*\*

\`\`\`bash curl -X POST <https://app.leadsonar.io/api/v1/find-email\\>
-H "Authorization: Bearer YOUR\_API\_KEY"\
-H "Content-Type: application/json"\
-d '{ "firstName": "Alex", "lastName": "Johnson", "website": "notion.so" }' \`\`\`

\*\*Response\*\*

\`\`\`json { "email": "<alex.johnson@notion.so>", "confidence": "high", "sources": 2, "credits\_used": 1 } \`\`\`

\*\*Credits:\*\* 1 per request

\---

\## POST /api/v1/find-phone

Find a direct-dial phone number for a person.

\*\*Request body\*\*

\| Field | Type | Required | Description | |-------|------|----------|-------------| | firstName | string | Yes | Contact's first name | | lastName | string | Yes | Contact's last name | | company | string | No | Company name | | website | string | No | Company domain |

\*\*Example\*\*

\`\`\`bash curl -X POST <https://app.leadsonar.io/api/v1/find-phone\\>
-H "Authorization: Bearer YOUR\_API\_KEY"\
-H "Content-Type: application/json"\
-d '{ "firstName": "Alex", "lastName": "Johnson", "company": "Notion" }' \`\`\`

\*\*Response\*\*

\`\`\`json { "phone": "+1-415-555-0192", "type": "direct", "credits\_used": 1 } \`\`\`

\*\*Credits:\*\* 1 per request

\---

\## POST /api/v1/enrich

Enrich multiple contacts in a single request. Returns a job ID — poll for results.

\*\*Request body\*\*

\| Field | Type | Required | Description | |-------|------|----------|-------------| | contacts | array | Yes | Array of contact objects (max 100) | | contacts\[].firstName | string | Yes | First name | | contacts\[].lastName | string | Yes | Last name | | contacts\[].website | string | Yes | Company domain | | contacts\[].companyName | string | No | Company name | | findEmail | boolean | No | Find email (default: true) | | findPhone | boolean | No | Find phone (default: false) |

\*\*Example\*\*

\`\`\`bash curl -X POST <https://app.leadsonar.io/api/v1/enrich\\>
-H "Authorization: Bearer YOUR\_API\_KEY"\
-H "Content-Type: application/json"\
-d '{ "contacts": \[\
{ "firstName": "Sarah", "lastName": "Chen", "website": "figma.com" },\
{ "firstName": "Mike", "lastName": "Lee", "website": "linear.app" }\
], "findEmail": true, "findPhone": true }' \`\`\`

\*\*Response\*\*

\`\`\`json { "jobId": "enr\_abc123", "status": "processing", "total": 2, "message": "Enrichment job started" } \`\`\`

\*\*Credits:\*\* 1 per contact per enrichment type

\---

\## GET /api/v1/enrich/:jobId

Poll the status of a bulk enrichment job.

\*\*Example\*\*

\`\`\`bash curl <https://app.leadsonar.io/api/v1/enrich/enr\\_abc123\\>
-H "Authorization: Bearer YOUR\_API\_KEY" \`\`\`

\*\*Response (completed)\*\*

\`\`\`json { "jobId": "enr\_abc123", "status": "completed", "total": 2, "completed": 2, "results": \[\
{\
"firstName": "Sarah",\
"lastName": "Chen",\
"email": "<sarah@figma.com>",\
"phone": "+1-415-555-0301",\
"confidence": "high"\
},\
{\
"firstName": "Mike",\
"lastName": "Lee",\
"email": "<mike@linear.app>",\
"phone": null,\
"confidence": "medium"\
}\
] } \`\`\`

\*\*Statuses:\*\* \`processing\`, \`completed\`, \`failed\`

\---

\## GET /api/v1/credits

Check your current credit balance.

\*\*Example\*\*

\`\`\`bash curl <https://app.leadsonar.io/api/v1/credits\\>
-H "Authorization: Bearer YOUR\_API\_KEY" \`\`\`

\*\*Response\*\*

\`\`\`json { "balance": 2450, "totalEarned": 3000, "totalSpent": 550 } \`\`\`

\---

\## GET /api/v1/providers

List available enrichment providers and their status.

\*\*Example\*\*

\`\`\`bash curl <https://app.leadsonar.io/api/v1/providers\\>
-H "Authorization: Bearer YOUR\_API\_KEY" \`\`\`

\---

\## Error codes

\| Status | Meaning | |--------|---------| | 400 | Bad request — check your request body | | 401 | Unauthorized — invalid or missing API key | | 402 | Insufficient credits | | 404 | Resource not found | | 429 | Rate limit exceeded — wait and retry | | 500 | Server error — contact support |

All error responses include a JSON body:

\`\`\`json { "error": "Description of what went wrong" } \`\`\`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://scalingroom.gitbook.io/leadsonar-docs/03-api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.