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. 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