---
title: "Check whether a person already exists before creating them"
method: POST
path: "/contacts/check-duplicates"
tags: ["contacts"]
---

# Check whether a person already exists before creating them

`POST /contacts/check-duplicates`

## Request

- Base URL: `https://withppl.com/api`
- URL: `https://withppl.com/api/contacts/check-duplicates`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://withppl.com/oauth/authorize`, token URL `https://withppl.com/oauth/token`)

## Request body

- object
  - `first_name` string: First name
  - `last_name` string: Last name
  - `email` string: Email

## Response `200`

OK

- object

## Other responses

- `400`: Bad request. Correct malformed JSON or unsupported query parameters. Do not repeat unchanged input. Optional agent_error adds recovery hints without replacing existing fields.
- `401`: Token invalid or authentication required. Refresh through OAuth when supported; otherwise reconnect with human approval. Never log the credential. Optional agent_error adds recovery hints without replacing existing fields.
- `403`: Access denied. For insufficient_scope, request owner-approved reconnection with the required permission. For agent_paused, ask the owner to resume it in My agents. For policy_denied, respect the policy; retrying will not grant access. Optional agent_error adds recovery hints without replacing existing fields.
- `404`: Resource or route not found. Check the documented route and resolve the intended record within this account. Do not try IDs from other accounts. Optional agent_error adds recovery hints without replacing existing fields.
- `409`: Conflict or approval_required. Resolve the conflict before retrying. REST cannot consume MCP approvals; request approval and execute the exact reviewed MCP tool with its approval_id. Optional agent_error adds recovery hints without replacing existing fields.
- `422`: Validation failed. Correct supplied fields using errors or error.message and the request schema. Do not repeat unchanged input. Optional agent_error adds recovery hints without replacing existing fields.
- `429`: Rate limited. Respect Retry-After when present; otherwise back off with jitter. Do not run parallel retries. Optional agent_error adds recovery hints without replacing existing fields.
- `500`: Server error. Back off. A failed write response does not prove the write was rolled back; check the outcome before retrying to avoid duplicates. Optional agent_error adds recovery hints without replacing existing fields.
- `503`: Temporarily unavailable or maintenance. Respect Retry-After when present and back off. Check the outcome of writes before replaying them. Optional agent_error adds recovery hints without replacing existing fields.

---

[API](https://skmtc.dev/ppl/apis/ppl-agent-api.md) · [All operations](https://skmtc.dev/ppl/apis/ppl-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ppl/apis/ppl-agent-api/revisions/01bf494abf73?raw)