Skip to content
AccountCloud Docs

Quickstart

Five minutes, a terminal with curl, and no cost: test keys are free.

The base URL of the API is https://api.accountcloud.io/v1.

1. Get a test key

Section titled “1. Get a test key”
  1. Sign up at app.accountcloud.io/signup with your work email address.
  2. Open the activation link we send you, and fill in your login and your company.
  3. At the end you see your test key, which starts with ac_test_. It is shown once, so copy it now. Lost it? Make a new one in the portal under API keys.

Put the key in an environment variable, so the commands below work as they are:

Terminal window
export ACCOUNTCLOUD_API_KEY="ac_test_…"

2. Check your key: GET /v1/me

Section titled “2. Check your key: GET /v1/me”
Terminal window
curl https://api.accountcloud.io/v1/me \
  -H "Authorization: Bearer $ACCOUNTCLOUD_API_KEY"
{
  "account": { "id": "acc_01m6hdz01g91yghfzyarpr76h8", "name": "Example B.V.", "status": "pending" },
  "environment": "test",
  "api_key": { "id": "key_01m6j19j146rd8ddxhf7cv0z0y", "name": "Default test key", "prefix": "ac_test_45QT", "expires_at": null },
  "scopes": ["*"],
  "balance": { "amount": "0.00", "currency": "EUR" }
}
  • environment is test: this key never reaches a real source and is never charged.
  • account.status is pending until we have verified your company, and active after that. Test keys work either way.
  • scopes is ["*"]: the key may call every operation. You can narrow that in the portal.
  • balance is your prepaid credit. Test calls never touch it.

GET /v1/me is free and needs no scope. A missing or wrong key gets 401 unauthenticated or invalid_api_key.

3. Call an operation: GET /v1/address/forms/NL

Section titled “3. Call an operation: GET /v1/address/forms/NL”

The address form of a country: which fields an address has there, in which order, which are required, and what the postcode looks like.

Terminal window
curl https://api.accountcloud.io/v1/address/forms/NL \
  -H "Authorization: Bearer $ACCOUNTCLOUD_API_KEY"
{
  "country": "NL",
  "verified": true,
  "fields": [
    {
      "id": "street",
      "label": "Street",
      "type": "text",
      "required": true,
      "max_length": 255,
      "options": null,
      "options_source": null,
      "example": null,
      "autocomplete": "address-line1",
      "layout": { "row": 1, "column": 1, "span": 8 }
    },
    {
      "id": "house_number",
      "label": "House number",
      "type": "text",
      "required": false,
      "max_length": 20,
      "options": null,
      "options_source": null,
      "example": null,
      "autocomplete": null,
      "layout": { "row": 1, "column": 2, "span": 2 }
    }
  ],
  "postcode": { "pattern": "[1-9]\\d{3} ?(?:[A-RT-Z][A-Z]|S[BCE-RT-Z])", "example": "1234 AB" },
  "subdivisions": []
}

The answer is shortened: the Netherlands has six fields. Try another country, such as BE or DE, or add ?locale=nl for Dutch labels. A country we do not support, such as US, gets 404 country_not_supported. The addresses guide explains every field.

4. See what it cost

Section titled “4. See what it cost”

Add -i to see the response headers:

Terminal window
curl -i https://api.accountcloud.io/v1/address/forms/NL \
  -H "Authorization: Bearer $ACCOUNTCLOUD_API_KEY"
HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Policy: "minute";q=60;w=60, "day";q=10000;w=86400
RateLimit: "minute";r=58;t=60, "day";r=9998;t=82610
AccountCloud-Charged: 0.0000
X-Request-Id: req_01m6j19mfvdxgsda7awkz3gzxk
  • AccountCloud-Charged is what the call cost, in euros. With a test key it is always 0.0000.
  • RateLimit says how many calls you have left this minute and today: 60 per minute for a test key. See rate limits.
  • X-Request-Id identifies the call. Both calls are now in the request log of the portal, marked as test. Quote the id when you contact support.

Next

Section titled “Next”
  • Build with test values. Every operation has fixed test values, including the error paths: see test mode.
  • Handle errors and retries. Read errors and idempotency: send an Idempotency-Key with every POST.
  • Go live. Once we have verified your company, you can make a live key (ac_live_…) and call the same URLs for real. See authentication and keys and pricing and credit.
  • Browse everything. The API reference lists every endpoint, and you can try each one there.

To check whether the API is up, without a key: curl https://api.accountcloud.io/v1/status, or see status.accountcloud.io.