Docs

Contact check

Set your contact check endpoint

PUT/v1/integration/contact-check-endpoint

Sets the HTTPS URL Alfa asks whether a person may be contacted. The first time, the answer includes the signing `secret`, shown only once; requests are signed with `Alfa-Signature` exactly like webhooks. A platform key sets one endpoint for each client company, named by `Alfa-Company-Id`. A URL that resolves to a private or internal address is 422 `invalid_webhook_url`. Before outbound sourcing first emails a person found for one of your jobs, Alfa sends your endpoint a signed `POST` (see the `contact-check` webhook) listing the people it is about to contact, each with a `ref` and the identifiers Alfa holds: `email`, `phone` and `linkedinUrl` (any can be null). Answer 200 with `{"results": [{"ref": "src_254928", "contactable": true}]}`, one entry for each `ref`, within 5 seconds. `contactable: false` stops that email and shows the candidate as not to be contacted. Alfa asks at the moment of sending and never caches an answer. Alfa fails closed: if your endpoint times out, cannot be reached, answers with a status other than 2xx, answers in another format, or gives no single clear answer for a person, the email is not sent and the recruiter can retry later. Requires an API key with the `webhooks:manage` scope.

Requires an Alfa API key as a bearer token. How API keys work

Headers

  • Alfa-Company-Idstring

    The Company ID of the company to act for. Required with a platform key, and that company must have authorized your platform; a company key acts for its own company and can leave it out.

Request body

  • urlstringrequired

    An HTTPS URL on the public internet.

    at most 2000 characters · format uri

Response body

  • keyIdintegerrequired

    The API key the endpoint belongs to.

  • companyIdstringrequired

    The company whose outreach it answers for.

  • urlstringrequired

    Where Alfa asks before contacting someone.

  • createdAtstringrequired

    When the endpoint was created.

  • updatedAtstringrequired

    When the endpoint last changed.

  • secretstring

    The signing secret, returned only when it is created or rotated. Store it; it is never shown again.

Responses

  • 200Success.
  • 400The request is malformed: invalid JSON, an unexpected body or an unknown query parameter. Problem details
  • 401The bearer token is missing, expired or invalid. Problem details
  • 403The caller may not perform this operation, or has no active organisation. Problem details
  • 404The resource does not exist or is not visible to the caller. Problem details
  • 422The request failed validation; `errors` lists each invalid field. Problem details
  • 429Too many requests, or the AI service is busy. Retry after a short wait. Problem details
  • 500An unexpected error. Quote the `correlationId` to support. Problem details