Users
A user stands for one of your customers and owns the codes you create for them. You identify users by your own external_ref; GP Code assigns the numeric id.
Users created through the API have no email or password and cannot log in to GP Code. Users are create-and-read only in v0. You often don't need POST /users at all: creating a code with a user object finds or creates the user in the same call.
The user object
GP Code's id for the user. Use it as user_id when creating codes.
Your own id for this customer. Unique within your partner account.
Display label. Defaults to "<partner name> · <external_ref>".
When the user was created.
Codes this user currently owns. Deleted codes are not counted.
{
"id": 8842,
"external_ref": "cust-4417",
"name": "Depot 4417",
"created_at": "2026-11-01T10:00:00+00:00",
"gp_codes_count": 2
}
Create a user
Creates a user for external_ref, or returns the existing one. The call is idempotent: if you already have a user with that external_ref, it is returned unchanged with 200 (its name is not overwritten). A new user returns 201.
Another partner using the same external_ref gets its own, unrelated user.
Body parameters
Your customer, booking or order id. Max. 191 characters. Must not contain @ — use an opaque id, not an email address.
Display label, max. 250 characters. Only used when the user is created.
Returns
201 with the new user, or 200 with the existing one.
Errors: 422 invalid_request (e.g. an email-like external_ref) · 403 forbidden_scope.
curl {{BASE}}/users \
-H "X-GoPeeko-Key: $GPCODE_KEY" \
-H "Authorization: Bearer $GPCODE_SECRET" \
-H "Content-Type: application/json" \
-d '{ "external_ref": "cust-4417", "name": "Depot 4417" }'
$res = $client->post('users', [
'json' => ['external_ref' => 'cust-4417', 'name' => 'Depot 4417'],
]);
$created = $res->getStatusCode() === 201;
$user = json_decode($res->getBody(), true)['data'];
const res = await fetch(`${BASE}/users`, {
method: 'POST',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({ external_ref: 'cust-4417', name: 'Depot 4417' }),
});
const created = res.status === 201;
const { data: user } = await res.json();
res = session.post(f"{BASE}/users", json={"external_ref": "cust-4417", "name": "Depot 4417"})
created = res.status_code == 201
user = res.json()["data"]
{
"data": {
"id": 8842,
"external_ref": "cust-4417",
"name": "Depot 4417",
"created_at": "2026-11-01T10:00:00+00:00",
"gp_codes_count": 0
}
}
List users
Your users, newest first, paginated.
Query parameters
Exact match. The quickest way to look up a user by your own id.
Page number. Default 1.
1–100. Default 25.
Returns
200 with data (array of users) and meta.
curl "{{BASE}}/users?external_ref=cust-4417" \
-H "X-GoPeeko-Key: $GPCODE_KEY" \
-H "Authorization: Bearer $GPCODE_SECRET"
$res = $client->get('users', ['query' => ['external_ref' => 'cust-4417']]);
$users = json_decode($res->getBody(), true)['data'];
const qs = new URLSearchParams({ external_ref: 'cust-4417' });
const res = await fetch(`${BASE}/users?${qs}`, { headers });
const { data: users, meta } = await res.json();
body = session.get(f"{BASE}/users", params={"external_ref": "cust-4417"}).json()
users, meta = body["data"], body["meta"]
{
"data": [
{
"id": 8842,
"external_ref": "cust-4417",
"name": "Depot 4417",
"created_at": "2026-11-01T10:00:00+00:00",
"gp_codes_count": 2
}
],
"meta": { "current_page": 1, "per_page": 25, "last_page": 1, "total": 1 }
}
Retrieve a user
One of your users by GP Code id.
Path parameters
The user's id.
Returns
200 with the user. 404 not_found if it is not one of yours.
To list a user's codes, call GET /gp-codes?user_id=….
curl {{BASE}}/users/8842 \
-H "X-GoPeeko-Key: $GPCODE_KEY" \
-H "Authorization: Bearer $GPCODE_SECRET"
$user = json_decode($client->get('users/8842')->getBody(), true)['data'];
const res = await fetch(`${BASE}/users/8842`, { headers });
const { data: user } = await res.json();
user = session.get(f"{BASE}/users/8842").json()["data"]
{
"data": {
"id": 8842,
"external_ref": "cust-4417",
"name": "Depot 4417",
"created_at": "2026-11-01T10:00:00+00:00",
"gp_codes_count": 2
}
}