JustCall

HOW in lib/justcall.py. Docs: developer.justcall.io/reference.

Auth & config

• Base URL: https://api.justcall.io/v2.1 · Auth: header Authorization: <api_key>:<api_secret>. Both come from JustCall > your profile > APIs and Webhooks. API access needs JustCall's Team plan or higher.
• Pagination: page / per_page; contacts, users and campaigns start at page 0. Max per_page: calls 100, texts 100, contacts 500, users 100, numbers 100, campaigns 50, list_calls_ai 20. A larger per_page is rejected, not trimmed. The next page is signalled by next_page_link.
• History: the API returns the last 3 months of calls.
• Rate limit (per account, by JustCall plan): Team 30/min and 1800/h, Pro 60/min, Business 90/min. Pace bulk work; a 429 means wait for the reset.

Operations

• Calls: list_calls (filter contact_number, agent_id, from_datetime/to_datetime as YYYY-MM-DD), get_call (fetch_ai_data=true adds AI fields), list_calls_ai, get_call_ai (transcript + summary + action items; needs JustCall's AI add-on).
• SMS: list_texts, get_text, check_reply (latest inbound text from a number, read-only), send_text (from one of your JustCall numbers; body up to 1600 characters; optional schedule_at YYYY-MM-DD HH:mm:ss; restrict_once="Yes" stops this text reaching the same number twice within 24h).
• Contacts: list_contacts (contact_number finds one by phone), get_contact, create_contact (contact_number + first_name required), update_contact (find by id or contact_number; notes are [{note}]).
• Team: list_users (agents and their numbers), get_user, list_phone_numbers (capabilities=sms for numbers that can text).
• Sales Dialer: list_campaigns, add_campaign_contact (campaign_id plus exactly one of contact_id or phone_number; optional name, email, custom_fields).

Phone numbers are E.164 (+14155550123). These are the only callable methods. There is no REST click-to-call for a human agent: load the list into a Sales Dialer campaign instead.

Guardrail

send_text, add_campaign_contact, create_contact and update_contact write to a live phone system: texts are billed by JustCall and reach real people, and a campaign contact gets dialled. Confirm before bulk; pilot one. The key is shared by the whole workspace, so send_text goes out from whichever justcall_number you pass: confirm the sending number with the user, it may be a colleague's line. A write that fails with "the write may have applied" may already have texted or queued the person: check list_texts, list_contacts or the campaign before resending, never resend blind.

Handoff

Read source: pull list_calls / get_call_ai and list_texts → write them as candidate activity into the ATS. Write target: send_text for a candidate nudge, add_campaign_contact to queue a shortlist for a calling session.

Callable surface

Call via the CLI: hyreflow tools execute justcall <method> --payload '{...}' (preview with --dry-run; hyreflow tools get justcall <method> returns the live contract + cost). Base: https://api.justcall.io/v2.1. Only the methods listed below are callable.

• add_campaign_contact(campaign_id: int, *, contact_id: int | None = None, phone_number: str | None = None, **fields) -> Any — POST /sales_dialer/campaigns/contact — queue a contact for dialing in a campaign (contact_id or phone_number).
• check_reply(contact_number: str, justcall_number: str | None = None) -> Any — POST /texts/checkreply — the latest inbound SMS from a contact (read-only).
• create_contact(payload: dict) -> Any — POST /contacts — create a contact (contact_number and first_name required).
  • requires: contact_number, first_name
  • example: {"contact_number":"+14155550123","first_name":"Jane","last_name":"Doe","company":"Acme"}
• get_call(call_id: str, **params) -> Any — GET /calls/{id} — one call by numeric id or call SID (fetch_ai_data=true adds AI fields).
• get_call_ai(call_id: int, *, fetch_transcription: bool = True, fetch_summary: bool = True, platform: str | None = None) -> Any — GET /calls_ai/{id} — transcript, summary, action items and sentiment for a call.
• get_contact(contact_id: int) -> Any
• get_text(text_id: int) -> Any
• get_user(user_id: int) -> Any
• list_calls(**params) -> Any — GET /calls — call log, filter by contact_number, agent_id, from_datetime/to_datetime (per_page max 100).
• list_calls_ai(**params) -> Any — GET /calls_ai — AI summaries for calls, filter by phone_number or dates (per_page max 20).
• list_campaigns(**params) -> Any — GET /sales_dialer/campaigns — Sales Dialer campaigns (page 0 is first; per_page max 50).
• list_contacts(**params) -> Any — GET /contacts — contacts, contact_number finds one by phone (page 0 is first; per_page max 500).
• list_phone_numbers(**params) -> Any — GET /phone-numbers — the account's JustCall numbers, filter by capabilities=sms (per_page max 100).
• list_texts(**params) -> Any — GET /texts — SMS history, filter by contact_number, justcall_number, sms_direction (per_page max 100).
• list_users(**params) -> Any — GET /users — agents with their numbers and availability (per_page max 100).
• send_text(justcall_number: str, contact_number: str, body: str, *, schedule_at: str | None = None, restrict_once: str | None = None, media_url: str | None = None) -> Any — POST /texts/new — send an SMS from a JustCall number (E.164 numbers; schedule_at 'YYYY-MM-DD HH:mm:ss').
• update_contact(payload: dict) -> Any — PUT /contacts — update a contact found by id or contact_number (notes are [{note}]).
  • example: {"contact_number":"+14155550123","company":"Acme"}