Skip to main content

Your First API Call

This guide walks you through making your first API call to GoRoute and understanding the response.

Check API Status​

Start by verifying the API is operational. The health check is unauthenticated:

Sandbox keys: if your API key starts with sk_test_, your account is on the test environment — use https://peppol-api-test.goroute.ai/peppol-api as the base URL and https://app-test.goroute.ai/app/ for the dashboard. The production URLs below are for pk_live_ keys.

curl -X GET https://app.goroute.ai/peppol-api/health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "environment": "production",
  "timestamp": "2026-01-25T14:29:55Z"
}

Lookup a Peppol Participant​

Query the Peppol network to check if a participant exists:

curl -X GET "https://app.goroute.ai/peppol-api/api/v1/participants/lookup?peppol_id=9915:testparticipant" \
  -H "X-API-Key: YOUR_API_KEY"

Response (Participant Found):

{
  "found": true,
  "participant_id": "9915:testparticipant",
  "name": "Test Organization",
  "country": "NL",
  "capabilities": [
    "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
  ]
}

Response (Participant Not Found):

{
  "found": false,
  "participant_id": "9915:unknown",
  "message": "Participant not found on the Peppol network."
}

Read Your Organization Profile​

An API key is bound to exactly one organization. Every request you make is scoped to that organization automatically — there is no organization ID to pass and no organization header to set. To read the profile of the organization behind your key:

curl -X GET https://app.goroute.ai/peppol-api/api/v1/settings/organization \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "id": "7c2f9a04-5d81-4b6e-8f3a-2b1c9d0e4f67",
  "name": "Acme Corporation",
  "peppol_id": "0106:12345678",
  "contact_name": "Jane Doe",
  "contact_email": "billing@acme.example",
  "vat_number": "NL123456789B01",
  "city": "Amsterdam",
  "country": "NL",
  "status": "active"
}
One key, one organization

There is no public endpoint for listing or creating organizations — an organization is provisioned during onboarding. Use PATCH /api/v1/settings/organization to update your own profile. If you serve several businesses, you get one API key per organization.

List Recent Transactions​

View your recent invoice transactions:

curl -X GET "https://app.goroute.ai/peppol-api/api/v1/transactions?page=1&page_size=5" \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "items": [
    {
      "id": "4b8e1c07-6a2d-4f51-9e3b-8c7d0a5f2b14",
      "direction": "sent",
      "status": "delivered",
      "document_type": "invoice",
      "sender_peppol_id": "0106:12345678",
      "receiver_peppol_id": "0204:DE987654321",
      "created_at": "2026-01-25T14:30:00Z",
      "delivered_at": "2026-01-25T14:30:12Z",
      "retry_count": 0
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 5,
  "pages": 1,
  "has_next": false,
  "has_prev": false
}

Understanding Responses​

Success Responses​

Status CodeMeaning
200 OKRequest successful
201 CreatedResource created successfully
202 AcceptedRequest accepted for processing
204 No ContentSuccess with no response body

Error Responses​

Status CodeMeaning
400 Bad RequestInvalid request syntax or parameters
401 UnauthorizedMissing or invalid API key
403 ForbiddenAPI key doesn't have permission
404 Not FoundResource doesn't exist
422 Unprocessable EntityValidation error
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorServer error (contact support)

Error Response Format​

Most errors return a flat object carrying the request ID:

{
  "error": "not_found",
  "error_code": "TRANSACTION_NOT_FOUND",
  "message": "Transaction 4b8e1c07-6a2d-4f51-9e3b-8c7d0a5f2b14 not found",
  "request_id": "req_9f2c1a7b4e6d40c8b1a3f5e7d9c02468"
}

A 422 Unprocessable Entity means the request body failed schema validation, and lists each offending field under detail:

{
  "detail": [
    {
      "loc": ["body", "invoice", "totals", "payable_amount"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
Request ID

Every response also carries an X-Request-ID header. Include that value (or the request_id from the error body) when contacting support — it helps us locate your specific request in our logs.

Common Request Headers​

HeaderRequiredDescription
X-API-KeyYesYour API key
Content-TypeFor POST/PUTapplication/json
AcceptNoResponse format (default: application/json)
Idempotency-KeyNoPrevent duplicate operations

Next Steps​

Now that you've made your first API call:

Last updated on