Aircall

HOW in lib/aircall.py. Docs: developer.aircall.io/api-references.

Auth & config

• Base URL: https://api.aircall.io/v1 · Auth: HTTP Basic — username=your Aircall API ID, password=your API Token (an Aircall admin generates them under Integrations > API keys; the token is shown once; never hardcode). (Multi-company partner apps use OAuth bearer — not in this adapter.)
• Pagination: page / per_page (max 50); iter_calls/iter_contacts auto-walk via meta.next_page_link. Calls & Contacts capped at 10,000 items total; history is 6 months.
• Rate limit: 120 req/min/company (watch X-AircallApi-Remaining).

Operations

Calls: list_calls/iter_calls, get_call, search_calls, tag_call, comment_call, get_transcription, get_call_summary. Contacts: list/iter/search/get/create/update/delete (phone_numbers & emails are [{label,value}]). Also list_users, dial, list_numbers, list_tags, webhooks, send_message (SMS). request() covers the rest.

Guardrail

dial, send_message, tag_call, comment_call are write/outbound actions on a live phone system — confirm before bulk; pilot one.

Handoff

Read source: pull call logs + transcripts/summaries → write as candidate activity into the ATS. Write target: comment_call to log recruiter notes; dial for click-to-call.

Callable surface — lib/aircall.py

Import: from lib.aircall import Aircall → instantiate Aircall() (reads key from env). Base: https://api.aircall.io/v1. Generic passthrough: request(method, path, *, params, json).

• comment_call(call_id: int, content: str) -> Any — POST /calls/{id}/comments — add a note to a call.
• create_contact(payload: dict) -> Any — POST /contacts — phone_numbers/emails are lists of {label,value}.
• create_webhook(url: str, *, events: list[str] | None = None, **params) -> Any — POST /webhooks — subscribe to events (e.g. call.created, call.ended).
• delete_contact(contact_id: int) -> Any
• delete_webhook(webhook_id: str) -> Any — DELETE /webhooks/{id} — remove a webhook subscription.
• dial(user_id: int, number: str) -> Any — POST /users/{id}/dial — push a number to a user's phone.
• get_call(call_id: int) -> Any
• get_call_summary(call_id: int) -> Any
• get_contact(contact_id: int) -> Any
• get_transcription(call_id: int) -> Any — GET /calls/{id}/transcription — call transcript (falls back to /realtime_transcription).
• iter_calls(**params) -> Iterator[dict]
• iter_contacts(**params) -> Iterator[dict]
• list_calls(**params) -> Any — GET /calls — historical calls (page/per_page; from/to UNIX, direction, etc.).
• list_contacts(**params) -> Any
• list_numbers(**params) -> Any
• list_tags(**params) -> Any
• list_users(**params) -> Any — GET /v2/users — users with default_number_id + availability (v1 users is deprecated).
• list_webhooks(**params) -> Any
• ping() -> Any — GET /ping — verify the API ID + token (returns {"ping": "pong"}).
• search_calls(**params) -> Any — GET /calls/search — filter calls (phone_number, user_id, tags, from/to...).
• search_contacts(**params) -> Any — GET /contacts/search — by phone_number / email.
• send_message(number_id: int, to: str, body: str) -> Any — POST /numbers/{id}/messages/native/send — send an SMS from an Aircall number (shows in its inbox).
• tag_call(call_id: int, tags: list[str]) -> Any — POST /calls/{id}/tags — apply tags to a call.
• update_contact(contact_id: int, payload: dict) -> Any — POST /contacts/{id} — update a contact (partial fields OK).