Mint CLI Signup Token

POST/v1/sign_up

Mints a one-shot cli_token and returns a prefilled signup URL. The user opens the URL, clears the captcha, accepts the Terms of Service and creates the account. The CLI then polls GET /sign_up/{cli_token} until the accounts service has propagated the new user and its first API key, at which point the API returns the credentials exactly once.

The API does not store the cli_token when it mints it. The token becomes known to the API only once the accounts service propagates the new user, so the CLI must set its own polling deadline. If the user never completes signup, GET /sign_up/{cli_token} returns 202 Accepted indefinitely.

Request body

Send a JSON object with the following fields. Account holder and organisation details are required:

• body object

  • email string required

    Account holder's email address.

    Format

    email

  • name string required

    Account holder's full name.

  • org_name string required

    Organisation name.

  • org_address_line_one string required
  • org_address_line_two string optional
  • org_address_line_three string optional
  • org_post_town string required
  • org_postcode string required
  • org_country_code string required

    ISO 3166-1 alpha-2 country code.

Response

result contains a cli_token (for polling) and a signup_url (for the user to complete signup).

• result object

  • cli_token string

    Random URL-safe token (base64url). Used by the CLI to poll for credentials.

  • signup_url string

    Prefilled accounts web URL. The user opens this in a browser to complete signup.

    Format

    uri

The result sits inside the standard { result, code, message } envelope — see the API reference for the wrapper format.

Flow

1. CLI calls POST /sign_up with account holder and organisation details
2. API returns cli_token and signup_url
3. CLI directs user to open signup_url in browser
4. User completes captcha, accepts Terms of Service, and creates account
5. Rails propagates new user to the API
6. CLI polls GET /sign_up/{cli_token} until credentials are returned
7. Credentials are returned exactly once; subsequent polls return 410 Gone

Request

curl

curl -X POST 'https://api.ideal-postcodes.co.uk/v1/sign_up' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "name": "Jane Smith",
    "org_name": "Example Corp",
    "org_address_line_one": "10 Example Street",
    "org_post_town": "London",
    "org_postcode": "SW1A 1AA",
    "org_country_code": "GB"
  }'

JavaScript

const response = await fetch('https://api.ideal-postcodes.co.uk/v1/sign_up', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    name: 'Jane Smith',
    org_name: 'Example Corp',
    org_address_line_one: '10 Example Street',
    org_post_town: 'London',
    org_postcode: 'SW1A 1AA',
    org_country_code: 'GB',
  }),
});

const { result } = await response.json();

Python

import requests

response = requests.post(
    "https://api.ideal-postcodes.co.uk/v1/sign_up",
    json={
        "email": "user@example.com",
        "name": "Jane Smith",
        "org_name": "Example Corp",
        "org_address_line_one": "10 Example Street",
        "org_post_town": "London",
        "org_postcode": "SW1A 1AA",
        "org_country_code": "GB",
    },
)
result = response.json()["result"]

Ruby

require "net/http"
require "json"

uri = URI("https://api.ideal-postcodes.co.uk/v1/sign_up")
body = {
  email: "user@example.com",
  name: "Jane Smith",
  org_name: "Example Corp",
  org_address_line_one: "10 Example Street",
  org_post_town: "London",
  org_postcode: "SW1A 1AA",
  org_country_code: "GB",
}
response = Net::HTTP.post(uri, body.to_json, "Content-Type" => "application/json")
result = JSON.parse(response.body)["result"]

PHP

<?php
$ch = curl_init("https://api.ideal-postcodes.co.uk/v1/sign_up");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode([
    "email" => "user@example.com",
    "name" => "Jane Smith",
    "org_name" => "Example Corp",
    "org_address_line_one" => "10 Example Street",
    "org_post_town" => "London",
    "org_postcode" => "SW1A 1AA",
    "org_country_code" => "GB",
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true)["result"];

Body

{
  "email": "",
  "name": "",
  "org_name": "",
  "org_address_line_one": "",
  "org_address_line_two": "",
  "org_address_line_three": "",
  "org_post_town": "",
  "org_postcode": "",
  "org_country_code": ""
}

Response

200 OK

{
  "code": 2000,
  "message": "Success",
  "result": {
    "cli_token": "",
    "signup_url": ""
  }
}

400 Bad Request

response.json

{
  "code": 4000,
  "message": "Invalid Request"
}