Look up a caller

A phone system can ask Auradonors who is calling and get back the page to open on the agent’s computer. 3CX does this through a template the organization downloads from Auradonors; any other phone system that can make an HTTP request can do the same.

The organization creates a connection key on its Phone system page in Auradonors (Enterprise Partner). It is not an API key: it reads one thing — who has a phone number — and is sent as a bearer token.

The request

curl https://api.auradonors.com/api/integrations/v1/{tenantSlug}/phone/lookup?number=%2B15551234567 \
  -H "Authorization: Bearer aura_…"

• tenantSlug is the organization’s short name, shown on its Phone system page.
• number may be in any format — +15551234567, (555) 123-4567, 011 44 20 7946 0958. It is matched exactly against every contact’s phone numbers; a US number is found whether it was saved with the leading 1 or without. Encode a leading + as %2B.
• A blank or withheld number answers 200 with match: "none".

The response

{
  "match": "one",
  "number": "15551234567",
  "openUrl": "https://app.auradonors.com/contacts/caller#n=15551234567&c=1042",
  "contacts": [
    {
      "id": 1042,
      "type": "Individual",
      "displayName": "Jane Donor",
      "firstName": "Jane",
      "lastName": "Donor",
      "organizationName": null,
      "matchedPhone": "5551234567",
      "openUrl": "https://app.auradonors.com/contacts/caller#n=15551234567&c=1042"
    }
  ]
}

• match is none, one or several.
• openUrl is the page to open: it finds the caller again in whichever environment the agent is signed in to, and opens the contact for one match or lists them for several. With several matches every contact’s openUrl is the list, so a phone system that takes the first contact still shows the agent all of them.
• contacts lists at most ten, best match first, with names only — no email, address or giving.

Errors

Status	When
401	The key is missing, malformed, replaced or belongs to another organization.
403	The organization’s plan doesn’t include a phone system, or the connection is switched off.
404	The organization’s short name isn’t known.
429	Too many lookups with one key in a minute.
503	The organization’s contacts couldn’t be reached in time. Try again shortly.

Each error body is a list of { code, description }.

Without a lookup

A phone system that can only open a web address can skip the lookup entirely: point it at https://app.auradonors.com/contacts/caller#n= followed by its placeholder for the caller’s number. The page does the lookup itself.