Look up beneficiary eligibility

Read the plans or affiliation validation messages for a document and service category. Plans do not establish coverage for a specific CUPS, authorization, or voucher amount.

Scope: axxa:eligibility:read
Credentials: an API key, a client-credentials token or a person's access token
Effect: read-only; safe to retry
Limits: request body up to 32 KB, response up to 256 KB
CLI: arbol axxa eligibility lookup · MCP tool: axxa_eligibility_lookup

POST

https://api.getarbol.com/v1/axxa/eligibility/lookup

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with the scope axxa:eligibility:read. Get an API key.

Request body JSON required

documentNumber
string
required
pattern: ^[A-Za-z0-9]{3,30}$
documentType
CC
or
CE
or
TI
or
RC
or
PA
required
serviceType
outpatient
or
emergency
or
laboratory
or
therapy
or
radiology
or
other
required
connectionId
optional
string
pattern: ^con_[0-9A-Za-z]{26}$

Returns

200

Successful operation.

JSON

success
true
required
data
object
required
Observed plan/validation result for this service category. This does not establish coverage for a CUPS, active authorization, or a voucher amount.
- status
  plans_found
  or
  validation_required
  required
- plans
  array of
  object
  required
  name
  string
  required
  maxLength: 300 · minLength: 1
  contractNumber
  string
  required
  maxLength: 100 · minLength: 1
  notice
  string | null
  required
  maxLength: 2000
- validationMessages
  array of
  string
  required
  maxLength: 2000 · minLength: 1
}
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.
}

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.
}

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.
}

403

FORBIDDEN: The token does not authorize this operation.
LOGIN_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.
ACCOUNT_MISMATCH: The portal session does not match the configured account and branch.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
ForbiddenFailure
FORBIDDEN
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.

AxxaLoginRejectedFailure
LOGIN_REJECTED
code
LOGIN_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.

AxxaAccountMismatchFailure
ACCOUNT_MISMATCH
code
ACCOUNT_MISMATCH
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.
}

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.
}

409

NOT_CONFIGURED: This organization has no AXA account configured. Contact your administrator.
SESSION_REQUIRED: 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.
SESSION_BUSY: 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:
AxxaNotConfiguredFailure
NOT_CONFIGURED
code
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.

AxxaSessionRequiredFailure
SESSION_REQUIRED
code
SESSION_REQUIRED
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.

AxxaSessionBusyFailure
SESSION_BUSY
code
SESSION_BUSY
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.
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

success
false
required
data
unknown
required
error
object
required
The request exceeds the allowed size.
- code
  REQUEST_TOO_LARGE
  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.
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

success
false
required
data
unknown
required
error
object
required
The request content type is not supported.
- code
  UNSUPPORTED_MEDIA_TYPE
  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.
}

428

CAPTCHA_REQUIRED: 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
object
required
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.
- code
  CAPTCHA_REQUIRED
  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.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.
LOGIN_COOLDOWN: 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:
RateLimitedFailure
RATE_LIMITED
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.

AxxaLoginCooldownFailure
LOGIN_COOLDOWN
code
LOGIN_COOLDOWN
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.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

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.
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.
PORTAL_CHANGED: 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.

AxxaPortalChangedFailure
PORTAL_CHANGED
code
PORTAL_CHANGED
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.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
CAPTCHA_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.
CAPTCHA_PAUSED: 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:
UpstreamUnavailableFailure
UPSTREAM_UNAVAILABLE
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.

AxxaCaptchaUnavailableFailure
CAPTCHA_UNAVAILABLE
code
CAPTCHA_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.

AxxaCaptchaPausedFailure
CAPTCHA_PAUSED
code
CAPTCHA_PAUSED
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.

AxxaPortalUnavailableFailure
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.
}

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.
}