SuperFront integrations · API v1

Integration API documentation

Connect a SuperFront workspace and find or create candidates by email. All requests and responses use JSON over HTTPS.

Authentication and workspace access

Production API base URL:

https://superfront-644796342855.europe-west2.run.app

Request a workspace API key from SuperFront support. Send it in the X-API-Key HTTP header on every request. This is a separate credential from your SuperFront password.

X-API-Key: YOUR_SUPERFRONT_API_KEY
Accept: application/json

A key is restricted to one workspace and these integration endpoints. It cannot sign in to the browser app or access admin endpoints. Keep it private, never put it in a URL, and ask support to revoke it when disconnecting an integration. Removing a connection in Zapier does not itself revoke the key in SuperFront.

GET /api/v1/me

Check the API key and identify its connected workspace. No request body is required.

curl 'https://superfront-644796342855.europe-west2.run.app/api/v1/me' \
  -H 'X-API-Key: YOUR_SUPERFRONT_API_KEY'

200 OK — connection verified

{
  "client_id": 123,
  "client_name": "Example workspace"
}

client_id is the integer workspace ID; client_name is its display name. The values above are examples.

POST /api/v1/candidates

Find a candidate by email within the key’s workspace. If no matching candidate exists, create one using the supplied first name, last name and email. The Zapier action is called Find Candidate.

Send Content-Type: application/json and exactly these three fields:

Required request fields
Field	Type	Rules
`first_name`	String	1–255 characters after trimming whitespace; no null characters.
`last_name`	String	1–255 characters after trimming whitespace; no null characters.
`email`	String	A valid email address; surrounding whitespace is trimmed and it is normalised to lowercase.

curl -X POST 'https://superfront-644796342855.europe-west2.run.app/api/v1/candidates' \
  -H 'X-API-Key: YOUR_SUPERFRONT_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"first_name":"Alex","last_name":"Example","email":"alex@example.com"}'

201 Created — new candidate

{
  "id": "00000000-0000-4000-8000-000000000001",
  "created": true
}

200 OK — existing candidate found

{
  "id": "00000000-0000-4000-8000-000000000001",
  "created": false
}

Both responses return id (the candidate’s UUID string) and created (a boolean). Matching is case-insensitive and limited to the connected workspace. An existing candidate’s details are left unchanged, even if you supply different names. Repeating a successful request with the same email returns the existing ID.

This endpoint does not assign candidates to campaigns or projects, send messages, or initiate outreach.

Error responses and troubleshooting

HTTP status codes
Status	Meaning and next step
401 Unauthorized	The API key is missing, invalid or revoked, or its issuing user is inactive. Check the header and ask support for a valid key.
403 Forbidden	The key’s issuing user no longer has access to the workspace. Ask support to check access.
422 Unprocessable Entity	Invalid JSON, a missing or invalid field, or an unexpected extra field. Correct the request using the validation details before retrying.
5xx Server Error	A temporary service failure. Retry with a delay; for candidate requests, use the same email to avoid a duplicate. Contact support if it persists.

Example authentication error:

{"detail":"Invalid or revoked API key"}

Validation errors contain a detail array describing the affected field and reason. Do not retry 401, 403 or 422 errors unchanged. Do not include your API key or candidate personal details in public support messages.

For the machine-readable schema, see the OpenAPI specification. For help connecting a workspace, email matthew@trysuperfront.com.