Docs / Get started

Getting started

From API key to a printed QR code in a few minutes. Every example on this site is available in cURL, PHP, Node.js and Python — pick a language once and all samples follow.

Before you begin

An API key (gpk_test_…) and secret (gps_…) for staging. GP Code sends you these when your partner account is set up — see Get access.
A server-side environment. The API is not meant to be called from a browser or mobile app: the secret must never reach end users.

Store both values as environment variables so the examples run as-is:


                export GPCODE_KEY="gpk_test_7f3a91c4b2e84d05"
                export GPCODE_SECRET="gps_your_secret_here"

Check your allowance

A good first call: it needs no scope, so it only tests that your key and secret work. It returns how many codes you can still create.


                        curl {{BASE}}/me/quota \
                          -H "X-GoPeeko-Key: $GPCODE_KEY" \
                          -H "Authorization: Bearer $GPCODE_SECRET"


                        $client = new GuzzleHttp\Client([
                            'base_uri' => '{{BASE}}/',
                            'headers'  => [
                                'X-GoPeeko-Key' => getenv('GPCODE_KEY'),
                                'Authorization' => 'Bearer ' . getenv('GPCODE_SECRET'),
                                'Accept'        => 'application/json',
                            ],
                        ]);

                        $quota = json_decode($client->get('me/quota')->getBody(), true)['data'];
                        echo $quota['usable_standard_codes'];


                        const BASE = '{{BASE}}';
                        const headers = {
                          'X-GoPeeko-Key': process.env.GPCODE_KEY,
                          Authorization: `Bearer ${process.env.GPCODE_SECRET}`,
                          Accept: 'application/json',
                        };

                        const res = await fetch(`${BASE}/me/quota`, { headers });
                        const { data: quota } = await res.json();
                        console.log(quota.usable_standard_codes);


                        import os, requests

                        BASE = "{{BASE}}"
                        session = requests.Session()
                        session.headers.update({
                            "X-GoPeeko-Key": os.environ["GPCODE_KEY"],
                            "Authorization": f"Bearer {os.environ['GPCODE_SECRET']}",
                            "Accept": "application/json",
                        })

                        quota = session.get(f"{BASE}/me/quota").json()["data"]
                        print(quota["usable_standard_codes"])

Create a code for a customer

Send a map pin (or an address) and your own reference for the customer. The user is created on the fly, the code is taken from the pool and is live immediately. Add an Idempotency-Key so a retry never creates a second code.


                        curl {{BASE}}/gp-codes \
                          -H "X-GoPeeko-Key: $GPCODE_KEY" \
                          -H "Authorization: Bearer $GPCODE_SECRET" \
                          -H "Content-Type: application/json" \
                          -H "Idempotency-Key: order-4417-a" \
                          -d '{
                            "type": "standard",
                            "lat": 35.8989,
                            "lng": 14.5146,
                            "location": "Front door",
                            "house_number": "5",
                            "user": { "external_ref": "cust-4417", "name": "Depot 4417" }
                          }'


                        $res = $client->post('gp-codes', [
                            'headers' => ['Idempotency-Key' => 'order-4417-a'],
                            'json'    => [
                                'type'         => 'standard',
                                'lat'          => 35.8989,
                                'lng'          => 14.5146,
                                'location'     => 'Front door',
                                'house_number' => '5',
                                'user'         => ['external_ref' => 'cust-4417', 'name' => 'Depot 4417'],
                            ],
                        ]);

                        $code = json_decode($res->getBody(), true)['data'];
                        echo $code['code'] . ' → ' . $code['url'];


                        const res = await fetch(`${BASE}/gp-codes`, {
                          method: 'POST',
                          headers: { ...headers, 'Content-Type': 'application/json', 'Idempotency-Key': 'order-4417-a' },
                          body: JSON.stringify({
                            type: 'standard',
                            lat: 35.8989,
                            lng: 14.5146,
                            location: 'Front door',
                            house_number: '5',
                            user: { external_ref: 'cust-4417', name: 'Depot 4417' },
                          }),
                        });

                        const { data: code } = await res.json();
                        console.log(code.code, '→', code.url);


                        res = session.post(
                            f"{BASE}/gp-codes",
                            headers={"Idempotency-Key": "order-4417-a"},
                            json={
                                "type": "standard",
                                "lat": 35.8989,
                                "lng": 14.5146,
                                "location": "Front door",
                                "house_number": "5",
                                "user": {"external_ref": "cust-4417", "name": "Depot 4417"},
                            },
                        )

                        code = res.json()["data"]
                        print(code["code"], "→", code["url"])


                        {
                          "data": {
                            "id": 91733,
                            "code": "12345",
                            "type": "standard",
                            "status": "active",
                            "location": "Front door",
                            "address": "Triq il-Kbira 5, Valletta",
                            "lat": 35.8989,
                            "lng": 14.5146,
                            "country": { "code": "MT", "name": "Malta" },
                            "owner": { "kind": "user", "user_id": 8842, "external_ref": "cust-4417" },
                            "url": "https://gpcode.com/12345",
                            "user_created": true,
                            "qr": { "format": "png", "encodes": "https://gpcode.com/12345", "data_url": "data:image/png;base64,iVBORw0…" },
                            "…": "…"
                          }
                        }

Show or print the QR

The response carries a 400×400 PNG as a data URL. Put it straight into an <img> tag, or decode the base64 part and save it as a file. The QR encodes url, the code's public page.
```
                        <img src="data:image/png;base64,iVBORw0…" width="200" height="200" alt="GP code 12345">
                        
```
Need it again later? Retrieve the code — single-code responses always include the QR unless you pass ?qr=false.

Next steps

Read Authentication to understand scopes, key rotation and IP allowlists.
See Create a code for every option: addresses, custom codes, detail fields and owners.
Handle failures with the error reference — branch on error.code, never on the message.
Import openapi.yaml into Postman, Insomnia or your code generator.

Getting started

Before you begin

Check your allowance

Create a code for a customer

Show or print the QR

Next steps