Create a contact
Add one person by email address.
POST
/api/v1/contactsScope
contacts:writeAdds a contact. The email address must be valid and not already used by another contact in your workspace — if it is, you get 409 and the message names the existing contact, so you can update it instead.
Body
Send a JSON object.
Prop
Type
Custom field values are checked against each field's type: a number field needs a number, a dropdown one of its options, a date YYYY-MM-DD. See Custom fields.
Example request
curl -X POST "https://api.pedibee.com/api/v1/contacts" \
-H "Authorization: Bearer $PEDIBEE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "jane@northwind.io",
"name": "Jane Cooper",
"title": "CTO",
"leadId": "66f1c2a9e4b0a1b2c3d4e001",
"listIds": [
"66f1c2a9e4b0a1b2c3d4e101"
],
"customFields": {
"plan": "Pro",
"seats": 25
}
}'Response
The new contact.
{
"id": "66f1c2a9e4b0a1b2c3d4e5f6",
"email": "jane@northwind.io",
"name": "Jane Cooper",
"title": "CTO",
"phone": "+1 555 0100",
"linkedIn": "https://www.linkedin.com/in/janecooper",
"notes": null,
"stage": "NEW",
"source": "MANUAL",
"verified": false,
"emailConfidence": 0,
"customFields": {
"plan": "Pro",
"seats": 25
},
"leadId": "66f1c2a9e4b0a1b2c3d4e001",
"listIds": [
"66f1c2a9e4b0a1b2c3d4e101"
],
"createdAt": "2026-10-05T09:30:00.000Z",
"updatedAt": "2026-10-05T09:30:00.000Z"
}Errors
Every error is { "error": "…" } with a message you can show. See Errors and limits.
| Status | When |
|---|---|
400 | The email is missing or invalid, a value is too long, the stage is unknown, or a custom field is unknown or has the wrong kind of value. |
403 | The key doesn’t have contacts:write, or its creator’s role no longer allows it. |
404 | leadId or one of listIds isn't in your workspace. |
409 | A contact with this email already exists. |
401 | The API key is missing, invalid, revoked or expired. |
429 | Too many requests. Wait for the seconds in Retry-After. |