Pin an end user to a paywall

Pins one end user, {identityType}:{identityValue} in the path, to a paywall at the location: they see its deployed build there whatever the location shows everyone else, and are outside an A/B test running there.

Replaces the end user's pin in that environment, answering 201 when there was none. A production pin answers every app; a test pin answers apps using a test key only and wins there. A pin shows only where the location shows something in that environment.

Guide: Paywalls in your app

Authorization

AuthorizationBearer <token>

A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.

In: header

Path parameters

projectId*string

The project's id, proj_.... A secret key works only in the project it belongs to.

paywallLocationId*string

The location's id, pw_loc_....

identity*string

The end user, as {identityType}:{identityValue} with the value percent-encoded, such as email:alice@example.com. The type is person_id, distinct_id or email.

Match^(?:person_id|distinct_id|email):[\s\S]*?$

Query parameters

environment?string

The environment the pin is for: production, the default, which answers every app, or test, which answers apps using a test key only and wins there.

Value in

"production"
"test"

Request body

application/json

TypeScript definitions

Use the request body type in TypeScript.

paywallId*string

The paywall to show the end user, pw_...; it must have a deployed build.

note?||

Why the pin exists, such as who is checking what, up to 255 characters. Omitted or null, the pin has no note.

Examples

curl -X PUT "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/paywall-locations/pw_loc_e2r5t8y1u4i7o0p3a6s9d2f5/pins/email:ada@example.com" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "paywallId": "pw_r3t6y9u2i5o8p1a4s7d0f3g6",    "note": "QA device for the monthly paywall"  }'

{  "id": "pw_loc_pin_e7h7d2k9m4x1c6v8b3n5q0w2",  "paywallLocationId": "pw_loc_e2r5t8y1u4i7o0p3a6s9d2f5",  "environment": "production",  "identityType": "email",  "identityValue": "ada@example.com",  "paywallId": "pw_r3t6y9u2i5o8p1a4s7d0f3g6",  "note": "QA device for the monthly paywall",  "createdAt": "2026-03-14T09:26:53.000Z"}

{  "id": "pw_loc_pin_e7h7d2k9m4x1c6v8b3n5q0w2",  "paywallLocationId": "pw_loc_e2r5t8y1u4i7o0p3a6s9d2f5",  "environment": "production",  "identityType": "email",  "identityValue": "ada@example.com",  "paywallId": "pw_r3t6y9u2i5o8p1a4s7d0f3g6",  "note": "QA device for the monthly paywall",  "createdAt": "2026-03-14T09:26:53.000Z"}

{  "error": {    "type": "invalid_request",    "code": "invalid_identity",    "message": "A pin names an end user by an identity of 1 to 255 characters.",    "param": "identity"  }}

{  "error": {    "type": "unauthenticated",    "code": "invalid_api_key",    "message": "This secret key is not valid."  }}

{  "error": {    "type": "permission_denied",    "code": "permission_denied",    "message": "Insufficient permissions."  }}

{  "error": {    "type": "not_found",    "code": "paywall_not_found",    "message": "This project has no paywall pw_h7d2k9m4x1c6v8b3n5q0w2e7.",    "param": "paywallId"  }}

{  "error": {    "type": "conflict",    "code": "paywall_not_deployed",    "message": "Paywall pw_h7d2k9m4x1c6v8b3n5q0w2e7 has no deployed build yet. Build it and deploy the build, then show it here.",    "param": "paywallId"  }}

{  "error": {    "type": "internal",    "code": "internal_error",    "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing."  }}

Response body

`application/json`

Errors

Status	`type`	`code`	When
400	`invalid_request`	`invalid_identity`	For an identity that is blank or longer than 255 characters.
404	`not_found`	`paywall_not_found`	When the project has no such paywall.
409	`conflict`	`paywall_not_deployed`	When the paywall has no deployed build.
409	`conflict`	`paywall_location_archived`	When the location is archived.
409	`conflict`	`paywall_location_pin_limit`	When the location already holds 200 pins.

It can also fail with the errors every operation shares, such as unauthenticated; see Errors.

More in Paywall locations

Guide: Paywalls in your app

Authorization

AuthorizationBearer <token>

A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.

In: header

Path parameters

projectId*string

The project's id, proj_.... A secret key works only in the project it belongs to.

paywallLocationId*string

The location's id, pw_loc_....

identity*string

The end user, as {identityType}:{identityValue} with the value percent-encoded, such as email:alice@example.com. The type is person_id, distinct_id or email.

Match^(?:person_id|distinct_id|email):[\s\S]*?$

Query parameters

environment?string

The environment the pin is for: production, the default, which answers every app, or test, which answers apps using a test key only and wins there.

Value in

"production"
"test"

Request body

application/json

TypeScript definitions

Use the request body type in TypeScript.

paywallId*string

The paywall to show the end user, pw_...; it must have a deployed build.

note?||

Why the pin exists, such as who is checking what, up to 255 characters. Omitted or null, the pin has no note.

Examples

curl -X PUT "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/paywall-locations/pw_loc_e2r5t8y1u4i7o0p3a6s9d2f5/pins/email:ada@example.com" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "paywallId": "pw_r3t6y9u2i5o8p1a4s7d0f3g6",    "note": "QA device for the monthly paywall"  }'

{  "id": "pw_loc_pin_e7h7d2k9m4x1c6v8b3n5q0w2",  "paywallLocationId": "pw_loc_e2r5t8y1u4i7o0p3a6s9d2f5",  "environment": "production",  "identityType": "email",  "identityValue": "ada@example.com",  "paywallId": "pw_r3t6y9u2i5o8p1a4s7d0f3g6",  "note": "QA device for the monthly paywall",  "createdAt": "2026-03-14T09:26:53.000Z"}

{  "id": "pw_loc_pin_e7h7d2k9m4x1c6v8b3n5q0w2",  "paywallLocationId": "pw_loc_e2r5t8y1u4i7o0p3a6s9d2f5",  "environment": "production",  "identityType": "email",  "identityValue": "ada@example.com",  "paywallId": "pw_r3t6y9u2i5o8p1a4s7d0f3g6",  "note": "QA device for the monthly paywall",  "createdAt": "2026-03-14T09:26:53.000Z"}

{  "error": {    "type": "invalid_request",    "code": "invalid_identity",    "message": "A pin names an end user by an identity of 1 to 255 characters.",    "param": "identity"  }}

{  "error": {    "type": "unauthenticated",    "code": "invalid_api_key",    "message": "This secret key is not valid."  }}

{  "error": {    "type": "permission_denied",    "code": "permission_denied",    "message": "Insufficient permissions."  }}

{  "error": {    "type": "not_found",    "code": "paywall_not_found",    "message": "This project has no paywall pw_h7d2k9m4x1c6v8b3n5q0w2e7.",    "param": "paywallId"  }}

{  "error": {    "type": "conflict",    "code": "paywall_not_deployed",    "message": "Paywall pw_h7d2k9m4x1c6v8b3n5q0w2e7 has no deployed build yet. Build it and deploy the build, then show it here.",    "param": "paywallId"  }}

{  "error": {    "type": "internal",    "code": "internal_error",    "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing."  }}

Response body

`application/json`

Errors

Status	`type`	`code`	When
400	`invalid_request`	`invalid_identity`	For an identity that is blank or longer than 255 characters.
404	`not_found`	`paywall_not_found`	When the project has no such paywall.
409	`conflict`	`paywall_not_deployed`	When the paywall has no deployed build.
409	`conflict`	`paywall_location_archived`	When the location is archived.
409	`conflict`	`paywall_location_pin_limit`	When the location already holds 200 pins.

It can also fail with the errors every operation shares, such as unauthenticated; see Errors.

Pin an end user to a paywall

paywall_not_found

project_not_found

paywall_not_deployed

paywall_location_archived

paywall_location_pin_limit

200application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

Pin an end user to a paywall

paywall_not_found

project_not_found

paywall_not_deployed

paywall_location_archived

paywall_location_pin_limit

200application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`