Peeker Partner API

Test with a sandbox key

Use a pk_test_... key while building the integration. Sandbox orders do not bill or run live fulfillment. Workspace credentials are shape-checked locally and receive a local sandbox identity. Peeker does not call the provider. Use placeholder credentials, never production secrets. Save Smartlead and PlusVibe login credentials through POST /workspaces. Smartlead’s login pair is optional when connecting, but its email and password must be sent together. Smartlead orders never accept login credentials. Google orders do not need the pair; Microsoft orders and pool attach do. Before going live, verify:

One successful order
One error response
Your webhook signature handler

A limited key can read data and check domain availability. Use a full key for other writes.

Log request IDs

Every response includes Peeker-Request-Id (opaque UUID). Errors include the same value as error.request_id.

{
	"error": {
		"code": "provider_credentials_invalid",
		"message": "Provider credentials were rejected",
		"request_id": "550e8400-e29b-41d4-a716-446655440000",
		"field": "credentials"
	}
}

Log the request ID, path, status, and error code. Never log bodies that contain provider credentials.

Handle errors by code

Branch on error.code, not message text.

Code	What to do
`invalid_request`	Correct the field named by `error.field`
`emailbison_super_admin_key`	Use an EmailBison workspace/user API key
`provider_credentials_invalid`	Correct or rotate the provider credentials
`provider_login_credentials_required`	Repair the provider login at its documented owner, then retry
`smartlead_client_not_found`	Check the Smartlead main key and target `client_id`
`workspace_promotion_required`	Repeat `POST /workspaces` with `promote_existing: true`
`workspace_credentials_conflict`	Reuse the workspace or rotate it with `PATCH /workspaces/{id}`
`idempotency_conflict`	Use the original body or a new key for a new order
`idempotency_in_progress`	Retry the same request shortly
`rate_limited`	Wait for the documented retry interval
`provider_unavailable` or `internal_error`	Retry with backoff and keep the request ID

Retry orders safely

POST /orders requires Idempotency-Key. POST /workspaces does not.

Generate one key from a stable checkout or order reference.
Keys are unique across your Partner account. Use a different key for each new order.
Keep the key with the checkout record.
Retry the unchanged order with the same key.
For a Smartlead Microsoft or PlusVibe login error, repair the connected workspace, then retry the unchanged order with its original key. Their orders reject destination.login_credentials.
Never reuse a key for another order or a changed request.

An exact order replay returns the original order with created.order: false. It does not charge again or emit duplicate completion webhooks.

Follow pagination links

List endpoints return links.first and links.next.

{
	"data": [],
	"links": {
		"first": "https://api.peeker.ai/partner/v1/orders?per_page=25",
		"next": "https://api.peeker.ai/partner/v1/orders?per_page=25&page_token=eyJ..."
	},
	"meta": {
		"path": "https://api.peeker.ai/partner/v1/orders",
		"per_page": 25,
		"returned": 25
	}
}

Follow links.next until it is null. links.next is a complete URL. Request that URL directly with your usual authorization header. If your client builds the request itself, extract only the URL’s page_token query parameter and keep the same filters. GET /orders also accepts the complete next-page URL as the page_token value for clients that already pass it that way. Other list endpoints require the token itself. Do not send the literal strings "null" or "undefined" after the last page. Do not build or decode page_token. Default page size is 25. Maximum is 100.

Keep webhook handlers small

Verify Peeker-Signature against the raw body.
Reject timestamps more than five minutes off.
Dedupe on Peeker-Event-Id for at least 24 hours.
Return 2xx quickly. Process from a queue.
Trust data.status. Do not depend on event order.

See Webhooks and Async jobs.

Concepts

Best practices

Test with a sandbox key

Log request IDs

Handle errors by code

Retry orders safely

Keep webhook handlers small

​Test with a sandbox key

​Log request IDs

​Handle errors by code

​Retry orders safely

​Follow pagination links

​Keep webhook handlers small

Test with a sandbox key

Log request IDs

Handle errors by code

Retry orders safely

Follow pagination links

Keep webhook handlers small