List registered professionals

List SURA's registered professionals for a service at this connection's institution, including doctors without published or free appointments. First obtain serviceId and optionally areaId from list_services. No patient identity is needed. Follow pageInfo.nextCursor while hasNextPage is true before concluding a name is absent from this scoped directory. Absence does not establish that a doctor does not exist or works nowhere else. Registration does not establish coverage, authorization, or availability: use prepare_appointment with the patient's evidence and the requested professional name to find actual slots. Never substitute another doctor without the patient's agreement. An unreadable or incomplete provider directory is a technical failure, not an empty list. A refusal, or a call still running, is the failure TOOL_REFUSED: data.reason says why, data.guidance what to do next and data.details what it offers instead (OPERATION_PENDING: poll data.details.operationId with operations.get); it is never an outage.

Scopes: any one of sura:appointments:read, sura:appointments:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: read-only; safe to retry
Limits: response up to 256 KB
CLI: arbol sura professionals list · MCP tool: sura_professionals_list

GET

https://api.getarbol.com/v1/sura/professionals

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with any one of the scopes sura:appointments:read, sura:appointments:write. Get an API key.

Query parameters

serviceId
string
required
Exact numeric service id returned by list_services. This directory is not filtered by patient coverage or available appointments.

pattern: ^[0-9]{1,20}$
areaId
optional
string | null
The areaId list_services returned beside that service. Pass it with an exact serviceId to skip a catalog lookup; omit it whenever you are naming the service in words.
cursor
optional
string
Opaque cursor returned by pageInfo; omit it to request the first page.
direction
optional
forward
or
backward
Direction to traverse the stable keyset ordering from the supplied cursor.

default: "forward"
limit
optional
integer
Maximum items returned in one page. Defaults to 25; larger reads require another cursor.

maximum: 100 · minimum: 1 · default: 25
agentMode
optional
boolean
Set agentMode=true when calling this tool for an AI agent. The answer is concise Spanish text instead of JSON. Omit it for structured machine data. This changes presentation only, never authorization, consent or idempotency.

default: false
connectionId
optional
string
Which of the organization's SURA connections to run on, by its id. Optional while the organization has one; required when it has several.

maxLength: 128 · minLength: 1
channel
optional
voice
or
whatsapp
or
web
The channel the caller is waiting on, which sets how long it waits before an answer comes back pending, and puts a phone call's reads ahead of others. Defaults to web.

Returns

200

Successful operation.

JSON

success
true
required
data
object
required
- data
  array of
  object
  required
  Items admitted by this resource contract within the verified organization.
  
  id
  string
  required
  Opaque directory identity. Use name, not this id, when requesting availability.
  
  name
  string
  required
  areaId
  string
  required
  serviceId
  string
  required
  serviceName
  string
  required
  registered
  boolean
  required
  availabilityChecked
  boolean
  required
- object
  string
  required
  Discriminator for a resource list response.
- pageInfo
  object
  required
  Opaque navigation cursors for this page’s stable keyset order.
  
  hasNextPage
  boolean
  required
  Whether a later page exists in the current ordering.
  
  hasPreviousPage
  boolean
  required
  Whether an earlier page exists in the current ordering.
  
  nextCursor
  string | null
  required
  Opaque cursor for the next page, or null when there is none.
  
  previousCursor
  string | null
  required
  Opaque cursor for the previous page, or null when there is none.
}
error
unknown
required
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

400

INVALID_INPUT: The request does not match the published schema.

JSON

success
false
required
data
unknown
required
error
object
required
The request does not match the published schema.
- code
  INVALID_INPUT
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  issues
  optional
  array of
  object
  path
  string
  required
  RFC 6901 JSON Pointer to the refused field; empty for the whole input.
  
  maxLength: 256
  message
  string
  required
  maxLength: 256
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

401

UNAUTHORIZED: A valid access token is required.

JSON

success
false
required
data
unknown
required
error
object
required
A valid access token is required.
- code
  UNAUTHORIZED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

403

FORBIDDEN: The token does not authorize this operation.

JSON

success
false
required
data
unknown
required
error
object
required
The token does not authorize this operation.
- code
  FORBIDDEN
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

404

CONNECTION_NOT_FOUND: The organization has no such connection.

JSON

success
false
required
data
unknown
required
error
object
required
The organization has no such connection.
- code
  CONNECTION_NOT_FOUND
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

409

PORTAL_SESSION_CONFLICT: The organization's connection to this integration couldn't complete the request. Don't retry it automatically; if it keeps happening, contact your Arbol team.
CONNECTION_NOT_CONFIGURED: The organization has no SURA connection that can run this operation.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
SuraPortalSessionConflictFailure
PORTAL_SESSION_CONFLICT
code
PORTAL_SESSION_CONFLICT
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
true
required
Whether repeating the same request may succeed.

SuraConnectionNotConfiguredFailure
CONNECTION_NOT_CONFIGURED
code
CONNECTION_NOT_CONFIGURED
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

422

TOOL_REFUSED: The request was not answered as a page: data.reason says why and data.guidance what to do next. Nothing was changed.

JSON

success
false
required
data
unknown
required
error
object
required
The request was not answered as a page: data.reason says why and data.guidance what to do next. Nothing was changed.
- code
  TOOL_REFUSED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  reason
  string
  required
  Why, as a stable code: NO_SERVICES, PORTAL_BUSY, OPERATION_PENDING…
  
  pattern: ^[A-Z][A-Z0-9_]{1,63}$
  detail
  string
  required
  What was refused, in English, for logs and people.
  
  details
  object
  required
  What the refusal offers to continue (the choices, the operation to poll), as the guidance names it.
  
  guidance
  optional
  string
  What an Agent does next, in the language it speaks to the person.
  
  say
  optional
  string
  A sentence an Agent may say to the person as it is.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

success
false
required
data
unknown
required
error
object
required
The request rate limit was exceeded. Try again later.
- code
  RATE_LIMITED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  true
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

success
false
required
data
unknown
required
error
object
required
The service could not complete the operation.
- code
  INTERNAL_ERROR
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.
PORTAL_CREDENTIALS_REJECTED: The organization's connection to this integration couldn't complete the request. Don't retry it automatically; if it keeps happening, contact your Arbol team.
PORTAL_UNAVAILABLE: The organization's connection to this integration couldn't complete the request. Don't retry it automatically; if it keeps happening, contact your Arbol team.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
OutcomeUnknownFailure
OUTCOME_UNKNOWN
code
OUTCOME_UNKNOWN
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.

SuraPortalCredentialsRejectedFailure
PORTAL_CREDENTIALS_REJECTED
code
PORTAL_CREDENTIALS_REJECTED
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

SuraPortalUnavailableFailure
PORTAL_UNAVAILABLE
code
PORTAL_UNAVAILABLE
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
true
required
Whether repeating the same request may succeed.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.

JSON

success
false
required
data
unknown
required
error
object
required
The upstream service could not complete the request.
- code
  UPSTREAM_UNAVAILABLE
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  true
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

success
false
required
data
unknown
required
error
object
required
The upstream service did not respond before its deadline.
- code
  UPSTREAM_TIMEOUT
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  true
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

PLAIN

string