API reference

Do not call

List, add and remove do-not-call numbers.

Overview

Your organization's do-not-call list. Finn never calls a listed number, from any deployment or single call.

Base URL: https://api.hirefinn.ai/api/v1. Auth: Authorization: Bearer finn_live_.... See authentication and scopes.

Endpoints

Method	Path	Scope	What it does
`GET`	`/do_not_call`	`voice:read`	The list, one entry per number, newest first. Pages with `limit` and `offset`.
`POST`	`/do_not_call`	`voice:write`	Add a number, with an optional `reason`. Its source is `api`.
`DELETE`	`/do_not_call/{phone}`	`voice:dnc:write`	Remove a number.

Adding a number the API already listed returns 200 with created: false. It is safe to retry.

Removing needs voice:dnc:write. A key with only voice:write gets 403 insufficient_scope. If the person asked not to be contacted (a call or chat opt-out), nothing is removed and the answer is 409 opted_out. Only an organization admin can remove those, in the dashboard.

All three share the read limit of 300 requests per minute per key.

Example

curl -X POST https://api.hirefinn.ai/api/v1/do_not_call \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550142", "reason": "Asked by email" }'

The answer has success, the entry as data, and created: true the first time, false if it was already listed.