Redeeming a code

Turn an agency's connect code into a connection, list your connections, and read one.

Redeem#

POST /connections with the code. There is no Idempotency-Key on this call.

http

POST /api/partners/v1/connections

json

{ "connect_code": "NK-7Q4M-X2PA-9KDF" }

Success, 201:

json

{ "connection": { "id": "9b1d6c2e-…", "status": "certifying", "environment": "sandbox",
    "agency": { "name": "Test agencija", "register_number": "123/2024", "verification_status": "verified",
                "listing_quota": { "used": 0, "limit": 50 }, "photo_limit": 30 },
    "created_at": "…", "redeemed_at": "…", "certified_at": null, "paused": null,
    "counts": { "live": 0, "paused": 0, "review": 0, "failed": 0 }, "last_push_at": null } }

Refusals:

json

404 { "error": { "code": "connect_code_invalid", "message": "The connect code is unknown, expired or already used." }, "request_id": "…" }
422 { "error": { "code": "agency_not_eligible", "message": "The agency can't connect yet.", "details": { "reason": "register_number_missing" } }, "request_id": "…" }

The code is normalised: accepted with or without the NK- prefix and the dashes, in any case.
One answer for every bad code. Unknown, expired, already used, and issued for another app all answer 404 connect_code_invalid, so a code cannot be probed.
A lost 201. If the response never reached you, a retry gets 404 (the code is used). Call GET /connections to find the new connection.
Environments. A sandbox key redeems only codes issued for a sandbox app; a live key only codes for your live app.

With the reference client:

node nk-partner.mjs redeem NK-7Q4M-X2PA-9KDF

List your connections#

http

GET /api/partners/v1/connections?status=active&limit=50

json

200 { "connections": [ Connection, … ], "next_cursor": "eyJ…" }

status filters; limit is 1–200; pass next_cursor back as cursor until it is null. Reference: GET /connections.

Read one#

http

GET /api/partners/v1/connections/9b1d6c2e-4f3a-4c8e-9a71-2d5e8f0b3c44

200 { "connection": Connection }; another app's id answers 404 connection_not_found. Reference: GET /connections/{id}.

Last updated 12 Oct 2026