Start connecting Xero
const url = 'https://api.elephants.inc/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/integrations/xero/authorize-url';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"return_path":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.elephants.inc/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/integrations/xero/authorize-url \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "return_path": "example" }'Mints the URL to send the user to in order to connect Xero. Send them there — a full page navigation, not a fetch, since Xero has to render its own consent screen.
Nothing is connected yet. The handshake completes when Xero redirects back
to this API, which exchanges the code, stores the credential, and then
sends the user on to return_path. Read GET /integrations afterwards to
confirm; the redirect carries no result of its own.
return_path is a path, not a URL — the origin is server
configuration, so no value here can send a user off-site. It must start
with a single /; a scheme, a protocol-relative //host, a backslash or
a control character is rejected. Omit it to use the default Xero setup
page.
The URL is single-purpose and short-lived; after expires_at it is
refused and a fresh one is needed.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Organization the connection will belong to
Request Bodyrequired
Section titled “Request Bodyrequired”Where to return the user
object
Same-origin path to return the user to once the handshake finishes. Must start with a single /; anything that could name a host is rejected.
Example generated
{ "return_path": "example"}Responses
Section titled “Responses”Where to send the user
object
After this the URL’s state is stale and the handshake will be refused.
Send the user here. Connecting completes on the redirect back.
Example generated
{ "expires_at": "2026-04-15T12:00:00Z", "url": "example"}Invalid request parameters or body
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}Too many requests
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
object
Example
{ "error": { "type": "rate_limited" }}Headers
Section titled “Headers”How long to wait before retrying, expressed as delay seconds or an HTTP date
Unexpected server error
Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.
Available verification methods
The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
Example generated
{ "error": { "details": "example", "message": "example", "request_id": "example", "step_up": { "delivery": "example", "expires_at": "2026-04-15T12:00:00Z", "id": "example", "match_code": "example", "methods": [ "example" ], "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "webauthn": { "allow_credentials": [ { "id": "example", "transports": [ "example" ], "type": "example" } ], "challenge": "example", "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rp_id": "example", "timeout": 1, "user_verification": "example" } }, "type": "example" }}