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. GET /health is the status check: it sits outside /api/v1, needs no API key, and tells you which environment the base URL resolves to.

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-08-06T06:09:57.050723"
}

The environment field is the authoritative answer to "which environment am I talking to" — the production base URL above answers "production", and the test base URL in the sandbox note answers "test". See Health Endpoints for readiness and liveness as well.

Code List Version

A separate endpoint reports the Peppol eDEC code list version the platform is currently using. It is useful for debugging and monitoring, and it is not an API version, an environment indicator or a status page:

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

Response:

{
  "version": "9.6",
  "publishedDate": "2026-04-07",
  "fetchedAt": "2026-06-25T05:35:05.347406",
  "active": true
}

Earlier revisions of this page published a response body that does not exist

This page used to show the code list version endpoint returning an environment name, an Access Point identifier and an operational status. It returns none of those — the four fields above are the whole response — and no endpoint on this API returns an Access Point identifier. Use /health for the environment.

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

List Your Organizations

Retrieve organizations associated with your API key:

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

Response:

{
  "organizations": [
    {
      "org_id": "org_abc123",
      "name": "Acme Corporation",
      "peppol_id": "0106:12345678",
      "country": "NL",
      "created_at": "2025-06-15T10:00:00Z",
      "status": "active"
    }
  ],
  "total": 1
}

List Recent Transactions

View your recent invoice transactions:

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

Response:

{
  "transactions": [
    {
      "transaction_id": "txn_xyz789",
      "direction": "outbound",
      "document_type": "invoice",
      "invoice_number": "INV-2026-001",
      "sender_id": "0106:12345678",
      "receiver_id": "0204:DE987654321",
      "status": "delivered",
      "created_at": "2026-01-25T14:30:00Z",
      "delivered_at": "2026-01-25T14:30:12Z"
    }
  ],
  "total": 1,
  "limit": 5,
  "offset": 0
}

Understanding Responses

Success Responses

Status Code	Meaning
200 OK	Request successful
201 Created	Resource created successfully
202 Accepted	Request accepted for processing
204 No Content	Success with no response body

Error Responses

Status Code	Meaning
400 Bad Request	Invalid request syntax or parameters
401 Unauthorized	Missing or invalid API key
403 Forbidden	API key doesn't have permission
404 Not Found	Resource doesn't exist
422 Unprocessable Entity	Validation error
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error (contact support)

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invoice validation failed",
    "details": [
      {
        "field": "receiver.peppol_id",
        "message": "Invalid Peppol identifier format"
      }
    ]
  },
  "request_id": "req_abc123"
}

Request ID

Always include the request_id when contacting support about an error. It helps us locate your specific request in our logs.

Common Request Headers

Header	Required	Description
X-API-Key	Yes	Your API key
Content-Type	For POST/PUT	application/json
Accept	No	Response format (default: application/json)
X-Idempotency-Key	No	Prevent duplicate operations

Next Steps

Now that you've made your first API call:

• Learn about environments
• Send your first invoice
• Set up webhooks