Developer API

Send leads into AI Phone

A simple REST API to push leads from your website forms, CRM, ad platforms, or automation tools (Zapier, Make, n8n) straight into your account. Every lead you send appears on your Contacts page and runs your posting instructions automatically.

Get your API key Jump to examples

Getting started

1.Create an API key
Open Dashboard → Developers and generate a key. Copy it right away — it's shown only once.
2.Point requests at the base URL
All endpoints live under https://voice.primeaxiom.ai/api/v1.
3.Send your first lead
POST to /public/leads with the X-API-Key header. That's it.

Authentication

Authenticate every request with your secret API key in the X-API-Key header. Keys are scoped to your account. Treat them like a password — never expose one in front-end/browser code. If a key leaks, revoke it from the dashboard and create a new one.

http

X-API-Key: ak_your_api_key_here

You can also pass the key as a bearer token: Authorization: Bearer ak_your_api_key_here.

POST/public/leads

Create a new lead. At least one of full_name, phone_number or email is required. Returns the stored lead, including its id and status.

Body parameters

Field	Type	Description	Required
`full_name`	string	The contact's full name.	One of name / phone / email required
`phone_number`	string	Phone number in any common format (e.g. +1 305 555 0198).	One of name / phone / email required
`email`	string	Email address.	One of name / phone / email required
`notes`	string	Free-form note or the message the lead submitted.	Optional
`source`	string	Where the lead came from — shown on the Contacts page. Defaults to "api".	Optional
`follow_up_time_text`	string	A human phrase for a requested callback, e.g. "tomorrow afternoon".	Optional
`custom_fields`	object	Any extra key/value data to store (company, budget, interest…).	Optional
`agent_id`	uuid	Associate the lead with a specific AI agent. Get IDs from GET /public/agents.	Optional
`lead_type_id`	uuid	Attach a custom lead type (form definition) id.	Optional

Example request

bash

curl -X POST "https://voice.primeaxiom.ai/api/v1/public/leads" \
  -H "X-API-Key: ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Jane Doe",
    "phone_number": "+13055550198",
    "email": "[email protected]",
    "source": "website",
    "notes": "Requested a quote for the Pro plan",
    "custom_fields": { "company": "Acme Corp", "budget": "$10k-$50k" }
  }'

Example response · 201

json

{
  "id": "9f1c2b3a-4d5e-6f70-8a9b-0c1d2e3f4a5b",
  "full_name": "Jane Doe",
  "phone_number": "+13055550198",
  "email": "[email protected]",
  "notes": "Requested a quote for the Pro plan",
  "source": "website",
  "status": "new",
  "agent_id": null,
  "lead_type_id": null,
  "custom_fields": { "company": "Acme Corp", "budget": "$10k-$50k" },
  "created_at": "2026-07-24T12:34:56.000Z"
}

GET/public/agents

List your AI agents so you can route a lead to a specific one via agent_id.

bash

curl "https://voice.primeaxiom.ai/api/v1/public/agents" \
  -H "X-API-Key: ak_your_api_key_here"

# → [ { "id": "…", "name": "Sales Bot", "status": "active" } ]

GET/public/ping

A lightweight check that your API key is valid. Returns your account id.

bash

curl "https://voice.primeaxiom.ai/api/v1/public/ping" \
  -H "X-API-Key: ak_your_api_key_here"

# → { "status": "ok", "tenant_id": "…", "timestamp": "…" }

Errors

Errors use standard HTTP status codes and return a JSON body of the form{ "detail": "…" }.

Status	detail	Meaning
`401`	Missing API key. Send it in the 'X-API-Key' header.	No key supplied.
`401`	Invalid or revoked API key.	The key is wrong or was revoked.
`403`	This account is not active.	The tenant is suspended or inactive.
`404`	Lead not found	The requested lead id does not exist for your account.
`422`	Provide at least one of: full_name, phone_number, email.	The lead payload had no identifying field.

Ready to connect your systems?

Generate an API key in your dashboard and start sending leads in minutes.

Create an API key