API reference

Account

Your profile, balance, preferences, team and account-level settings.

34 operationsBase URL https://packetexchange.io/api/v1Postman collection

BrowseAccount

Get your account profile

GET/api/v1/account

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Profile, balance and account state. Secrets are never included.

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`email`requireddata.email	string (email)	-
`contactName`requireddata.contactName	string	-
`companyName`requireddata.companyName	string \| null	-
`jobTitle`requireddata.jobTitle	string \| null	-
`phone`requireddata.phone	string \| null	-
`country`requireddata.country	string \| null	ISO-3166-1 alpha-2
`timezone`requireddata.timezone	string	-
`companyLogoUrl`requireddata.companyLogoUrl	string \| null	-
`avatarUrl`requireddata.avatarUrl	string \| null	-
`role`requireddata.role	string	-One of `user`, `admin`
`status`requireddata.status	string	-One of `active`, `suspended`
`accountKind`requireddata.accountKind	string	-
`balance`requireddata.balance	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`testCredit`requireddata.testCredit	money	Sandbox credit, spendable only by test API keys USD as a decimal string with exactly 6 places, e.g. "0.012500".
`emailVerifiedAt`requireddata.emailVerifiedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`pendingEmail`requireddata.pendingEmail	string \| null	An address change waiting for confirmation
`verificationStatus`requireddata.verificationStatus	string	-One of `unverified`, `verified`
`kycStatus`requireddata.kycStatus	string	-One of `not_started`, `pending`, `verified`, `rejected`
`totpEnabled`requireddata.totpEnabled	boolean	Two-factor authentication is on
`taxId`requireddata.taxId	string \| null	-
`taxCountry`requireddata.taxCountry	string \| null	-
`payoutMethod`requireddata.payoutMethod	string \| null	-
`onboardingGoal`requireddata.onboardingGoal	string \| null	-
`onboardingDismissed`requireddata.onboardingDismissed	boolean	-
`onboardingSeen`requireddata.onboardingSeen	boolean	-
`emailNotificationsOptOut`requireddata.emailNotificationsOptOut	boolean	-
`switchStatus`requireddata.switchStatus	string	-One of `none`, `active`, `past_due`, `canceled`, `comp`
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Update your account profile

PUT/api/v1/account

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Every field is optional; send only what changes. An empty string clears an optional text field. Session only because it can change the payout destination.

Request body (application/json)

Field	Type	Description
`companyName`	string	-max 255 chars
`contactName`	string	-max 255 chars
`companyLogoUrl`	string	-max 400000 chars
`jobTitle`	string	-max 120 chars
`avatarUrl`	string	-max 400000 chars
`phone`	string	-max 20 chars
`country`	string	-max 2 chars
`timezone`	string	-max 50 chars
`taxId`	string	-max 64 chars
`taxCountry`	string	-max 2 chars
`payoutMethod`	string	-
`payoutCryptoToken`	string	-max 20 chars
`payoutCryptoNetwork`	string	-max 40 chars
`payoutCryptoAddress`	string	-max 120 chars
`payoutWireDetails`	string	-max 2000 chars
`emailNotificationsOptOut`	boolean	-

Response 200

Field	Type	Description
`data`required	object	Same fields as AccountProfile, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/account" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "companyName": "Acme",
  "contactName": "<contactName>"
}'

Session-only: run it from the dashboard.

Get one headline figure per workspace

GET/api/v1/account/hub-stats

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Counts for the post-login hub. A figure that cannot be computed is null, never a guess.

Response 200

Field	Type	Description
`data`required	object	-
`trade`requireddata.trade	number \| null	-
`switch`requireddata.switch	number \| null	-
`outbound`requireddata.outbound	number \| null	-
`revenue-numbers`requireddata.revenue-numbers	number \| null	-
`numbers-store`requireddata.numbers-store	number \| null	-
`developers`requireddata.developers	number \| null	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get which walkthrough steps the account has completed

GET/api/v1/account/guide-progress

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Each key is a step signal derived from real data (a route exists, a call was made), true or false.

Response 200

Field	Type	Description
`data`required	object	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Request an email address change

POST/api/v1/account/email

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Needs the current password. Sends a confirmation link to the new address; the address changes only when it is confirmed. The old address is told.

Request body (application/json)

Field	Type	Description
`newEmail`required	string (email)	-max 255 chars
`currentPassword`required	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`email`requireddata.email	string (email)	-
`contactName`requireddata.contactName	string	-
`companyName`requireddata.companyName	string \| null	-
`jobTitle`requireddata.jobTitle	string \| null	-
`phone`requireddata.phone	string \| null	-
`country`requireddata.country	string \| null	ISO-3166-1 alpha-2
`timezone`requireddata.timezone	string	-
`companyLogoUrl`requireddata.companyLogoUrl	string \| null	-
`avatarUrl`requireddata.avatarUrl	string \| null	-
`role`requireddata.role	string	-One of `user`, `admin`
`status`requireddata.status	string	-One of `active`, `suspended`
`accountKind`requireddata.accountKind	string	-
`balance`requireddata.balance	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`testCredit`requireddata.testCredit	money	Sandbox credit, spendable only by test API keys USD as a decimal string with exactly 6 places, e.g. "0.012500".
`emailVerifiedAt`requireddata.emailVerifiedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`pendingEmail`requireddata.pendingEmail	string \| null	An address change waiting for confirmation
`verificationStatus`requireddata.verificationStatus	string	-One of `unverified`, `verified`
`kycStatus`requireddata.kycStatus	string	-One of `not_started`, `pending`, `verified`, `rejected`
`totpEnabled`requireddata.totpEnabled	boolean	Two-factor authentication is on
`taxId`requireddata.taxId	string \| null	-
`taxCountry`requireddata.taxCountry	string \| null	-
`payoutMethod`requireddata.payoutMethod	string \| null	-
`onboardingGoal`requireddata.onboardingGoal	string \| null	-
`onboardingDismissed`requireddata.onboardingDismissed	boolean	-
`onboardingSeen`requireddata.onboardingSeen	boolean	-
`emailNotificationsOptOut`requireddata.emailNotificationsOptOut	boolean	-
`switchStatus`requireddata.switchStatus	string	-One of `none`, `active`, `past_due`, `canceled`, `comp`
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`pendingVerification`requireddata.pendingVerification	boolean	-One of `true`

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/account/email" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "newEmail": "you@example.com",
  "currentPassword": "<currentPassword>"
}'

Session-only: run it from the dashboard.

Confirm an email change from a signed-in session

POST/api/v1/account/email/confirm

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Same effect as the public POST /auth/confirm-email-change, which is what the emailed link uses.

Request body (application/json)

Field	Type	Description
`token`required	string	-

Response 200

Field	Type	Description
`data`required	object	-
`email`requireddata.email	string (email)	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/account/email/confirm" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "<token>"
}'

Session-only: run it from the dashboard.

List recent security activity

GET/api/v1/account/activity

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

The latest 50 security events on the account (sign-ins, password and key changes), newest first.

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`type`requireddata[].type	string	e.g. login, password_change, api_key_created, session_revoked
`ip`requireddata[].ip	string \| null	-
`userAgent`requireddata[].userAgent	string \| null	-
`meta`requireddata[].meta	object \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Export all your account data

GET/api/v1/account/export

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

A data-protection export of everything held about the account. JSON by default (served as an attachment); format=xlsx returns a workbook with one sheet per dataset.

Parameters

Name	In	Type	Description
`format`	query	string	-One of json, xlsx, excel

Response 200

Field	Type	Description
`data`required	object	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Close your account

POST/api/v1/account/close

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Needs the password (and a 2FA code when 2FA is on). Personal data is anonymised; financial records are kept. A balance under the payout minimum can only be closed by opting in to forfeitBalance and echoing the exact forfeitAmountUsd from GET /account/close/preview.

Request body (application/json)

Field	Type	Description
`password`required	string	-
`code`	string	-
`forfeitBalance`	boolean	-
`confirmForfeitAmountUsd`	number \| string	-

Response 200

Field	Type	Description
`data`required	object	-
`message`requireddata.message	string	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/account/close" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "password": "correct-horse-battery-staple"
}'

Session-only: run it from the dashboard.

Preview what closing the account would take

GET/api/v1/account/close/preview

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

What is withdrawable, held or would be forfeited, and whether the account can be closed now.

Response 200

Field	Type	Description
`data`required	object	-
`balanceUsd`requireddata.balanceUsd	string	USD, 2-decimal string
`heldUsd`requireddata.heldUsd	string	Held back because it came from a recent card top-up
`withdrawableUsd`requireddata.withdrawableUsd	string	-
`minWithdrawalUsd`requireddata.minWithdrawalUsd	number	-
`pendingPayouts`requireddata.pendingPayouts	integer	-
`revshareEarningsUsd`requireddata.revshareEarningsUsd	string	-
`pendingRevsharePayouts`requireddata.pendingRevsharePayouts	integer	-
`canCloseNow`requireddata.canCloseNow	boolean	-
`canWithdraw`requireddata.canWithdraw	boolean	-
`revshareCanWithdraw`requireddata.revshareCanWithdraw	boolean	-
`forfeitRequired`requireddata.forfeitRequired	boolean	The only way out is to give up an amount stuck under the payout minimum
`forfeitBalanceUsd`requireddata.forfeitBalanceUsd	string \| null	-
`forfeitRevshareUsd`requireddata.forfeitRevshareUsd	string \| null	-
`forfeitAmountUsd`requireddata.forfeitAmountUsd	string \| null	Echo this exact figure as confirmForfeitAmountUsd to close with a forfeit
`message`requireddata.message	string	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Save your onboarding goal

POST/api/v1/account/onboarding

Access: API key. Scoped keys need account:write.
Rate limit: 100 requests per second (the default)

Records the first-run goal, or marks the welcome wizard seen or dismissed.

Request body (application/json)

Field	Type	Description
`goal`	string	-One of `buyer`, `seller`, `developer`, `reseller`
`dismissed`	boolean	-
`seen`	boolean	-

Response 200

Field	Type	Description
`data`required	object	Same fields as AccountProfile, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/account/onboarding" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "goal": "buyer",
  "dismissed": true
}'

Run it here with a test key.

Get your balance and test credit

GET/api/v1/account/balance

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Response 200

Field	Type	Description
`data`required	object	-
`balance`requireddata.balance	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`testCredit`requireddata.testCredit	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`total`requireddata.total	money	balance + testCredit USD as a decimal string with exactly 6 places, e.g. "0.012500".

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get your Switch plan and trial status

GET/api/v1/account/switch-subscription

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Works without a Switch plan: this is how an account finds out it has none.

Response 200

Field	Type	Description
`data`required	object	-
`active`requireddata.active	boolean	May this account use the Switch right now
`status`requireddata.status	string	-One of `none`, `active`, `past_due`, `canceled`, `comp`
`accessUntil`requireddata.accessUntil	string (date-time) \| null	ISO-8601 timestamp (UTC)
`comp`requireddata.comp	boolean	-
`nodeNft`requireddata.nodeNft	boolean	Access comes from a held Switch Node NFT
`priceUsd`requireddata.priceUsd	number	Monthly plan price in USD (a number, not a ledger amount)
`plan`requireddata.plan	string	-
`purchasablePlans`requireddata.purchasablePlans	string[]	-One of `starter`, `essentials`, `standard`, `growth`, `carrier`
`onTrial`requireddata.onTrial	boolean	-
`trialEndsAt`requireddata.trialEndsAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`trialEligible`requireddata.trialEligible	boolean	-
`trialDays`requireddata.trialDays	integer	-
`trialApplication`requireddata.trialApplication	object \| null	-
`id`requireddata.trialApplication.id	string (uuid)	-
`status`requireddata.trialApplication.status	string	-One of `pending`, `approved`, `declined`
`desiredPlan`requireddata.trialApplication.desiredPlan	string	-
`submittedAt`requireddata.trialApplication.submittedAt	string (date-time)	ISO-8601 timestamp (UTC)
`reviewedAt`requireddata.trialApplication.reviewedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`firstChargeDeferredTo`requireddata.firstChargeDeferredTo	string (date-time) \| null	ISO-8601 timestamp (UTC)
`cancelAt`requireddata.cancelAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`manageable`requireddata.manageable	boolean	Has a card subscription that the billing portal can manage

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Start a Switch subscription checkout

POST/api/v1/account/switch-subscription/checkout

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 10 requests per 5 minutes
Moves money: Starts a paid Switch subscription checkout.

Returns a card checkout url to open, and when the first charge falls. Answers { alreadyActive: true } when the account already has the Switch, or { alreadySubscribed: true } when a subscription exists that our record had not caught up with.

Request body (application/json)

Field	Type	Description
`plan`	string	-default "standard"One of `starter`, `essentials`, `standard`, `growth`, `carrier`

Response 200

Field	Type	Description
`data`required	object	-
`url`data.url	string (uri)	-
`firstChargeAt`data.firstChargeAt	string (date-time)	ISO-8601 timestamp (UTC)
`alreadyActive`data.alreadyActive	boolean	-One of `true`
`alreadySubscribed`data.alreadySubscribed	boolean	-One of `true`

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
AlsoSWITCH_BILLING_UNCONFIGURED, SWITCH_PRICE_MISMATCH

HTTP

curl -X POST "https://packetexchange.io/api/v1/account/switch-subscription/checkout" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "plan": "standard"
}'

Session-only: run it from the dashboard.

Get your Switch free-trial application

GET/api/v1/account/switch-trial-application

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Eligibility, the latest application if any, and profile values to prefill the form.

Response 200

Field	Type	Description
`data`required	object	-
`eligible`requireddata.eligible	boolean	-
`trialDays`requireddata.trialDays	integer	-
`hasSwitch`requireddata.hasSwitch	boolean	-
`comp`requireddata.comp	boolean	-
`onTrial`requireddata.onTrial	boolean	-
`trialEndsAt`requireddata.trialEndsAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`application`requireddata.application	object \| null	-
`id`requireddata.application.id	string (uuid)	-
`status`requireddata.application.status	string	-One of `pending`, `approved`, `declined`
`desiredPlan`requireddata.application.desiredPlan	string	-
`submittedAt`requireddata.application.submittedAt	string (date-time)	ISO-8601 timestamp (UTC)
`reviewedAt`requireddata.application.reviewedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`grantedPlan`requireddata.application.grantedPlan	string \| null	-
`trialEndsAt`requireddata.application.trialEndsAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`prefill`requireddata.prefill	object	-
`companyName`requireddata.prefill.companyName	string	-
`contactName`requireddata.prefill.contactName	string	-
`country`requireddata.prefill.country	string	-
`contactPhone`requireddata.prefill.contactPhone	string	-
`contactRole`requireddata.prefill.contactRole	string	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Apply for a Switch free trial

POST/api/v1/account/switch-trial-application

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 5 requests per 10 minutes

Our team reviews every application by hand. Refused with CONFLICT when the account already has the Switch or an application is pending.

Request body (application/json)

Field	Type	Description
`companyName`required	string	-max 255 chars
`companyWebsite`	string \| null	-max 255 chars
`country`	string \| null	-
`contactName`required	string	-max 255 chars
`contactRole`	string \| null	-max 120 chars
`contactPhone`	string \| null	-max 40 chars
`desiredPlan`required	string	-One of `starter`, `essentials`, `standard`, `growth`, `carrier`
`expectedCps`	integer \| null	-0 to 100000
`expectedChannels`	integer \| null	-0 to 10000000
`expectedMonthlyMinutes`	integer \| null	-0 to 100000000000
`trafficProfile`	string \| null	-max 2000 chars
`currentSetup`	string \| null	-max 2000 chars
`notes`	string \| null	-max 4000 chars

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`status`requireddata.status	string	-One of `pending`, `approved`, `declined`
`submittedAt`requireddata.submittedAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/account/switch-trial-application" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "companyName": "Acme",
  "contactName": "<contactName>",
  "desiredPlan": "starter"
}'

Session-only: run it from the dashboard.

Open the Switch billing portal

POST/api/v1/account/switch-subscription/portal

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 10 requests per 5 minutes

Returns a URL where the card, cancellation and invoices of the Switch subscription are managed.

Response 200

Field	Type	Description
`data`required	object	-
`url`requireddata.url	string (uri)	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
AlsoSWITCH_NO_SUBSCRIPTION

HTTP

curl -X POST "https://packetexchange.io/api/v1/account/switch-subscription/portal" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN"

Session-only: run it from the dashboard.

Start two-factor authentication setup

POST/api/v1/account/2fa/setup

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Generates a pending secret and an otpauth:// URI for an authenticator app. Nothing changes until POST /account/2fa/enable confirms a code.

Response 200

Field	Type	Description
`data`required	object	-
`secret`requireddata.secret	string	-
`otpauthUri`requireddata.otpauthUri	string	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Turn on two-factor authentication

POST/api/v1/account/2fa/enable

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Confirms a code from the authenticator and returns one-time backup codes, shown only this once.

Request body (application/json)

Field	Type	Description
`code`required	string	6-digit authenticator code

Response 200

Field	Type	Description
`data`required	object	-
`backupCodes`requireddata.backupCodes	string[]	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/account/2fa/enable" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "482913"
}'

Session-only: run it from the dashboard.

Turn off two-factor authentication

POST/api/v1/account/2fa/disable

Access: Dashboard session. API keys are refused with 403. Use a login access token.
Rate limit: 100 requests per second (the default)

Request body (application/json)

Field	Type	Description
`code`	string	-
`password`	string	-

Response 200

Field	Type	Description
`data`required	object	Same fields as Message, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/account/2fa/disable" \
  -H "Authorization: Bearer $PACKETEXCHANGE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "482913",
  "password": "correct-horse-battery-staple"
}'

Session-only: run it from the dashboard.

Get your spend alert settings

GET/api/v1/account/alerts

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Defaults (no thresholds, email on) when nothing has been saved.

Response 200

Field	Type	Description
`data`required	object	-
`lowBalanceThreshold`requireddata.lowBalanceThreshold	string \| null	USD, 2-decimal string; null = no low-balance alert
`dailySpendCap`requireddata.dailySpendCap	string \| null	USD, 2-decimal string; null = no daily cap alert
`notifyEmail`requireddata.notifyEmail	boolean	-
`updatedAt`requireddata.updatedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Update your spend alert settings

PUT/api/v1/account/alerts

Access: API key. Scoped keys need account:write.
Rate limit: 100 requests per second (the default)

Send at least one field. Thresholds are USD amounts; null removes one.

Request body (application/json)

Field	Type	Description
`lowBalanceThreshold`	number \| null	-min 0
`dailySpendCap`	number \| null	-min 0
`notifyEmail`	boolean	-

Response 200

Field	Type	Description
`data`required	object	Same fields as AccountSpendAlerts, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/account/alerts" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lowBalanceThreshold": 1,
  "dailySpendCap": 1
}'

Run it here with a test key.

List your saved marketplace searches

GET/api/v1/account/saved-searches

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`userId`requireddata[].userId	string (uuid)	-
`name`requireddata[].name	string	-
`filters`requireddata[].filters	object	Marketplace filter values, as the marketplace query parameters
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Save a marketplace search

POST/api/v1/account/saved-searches

Access: API key. Scoped keys need account:write.
Rate limit: 100 requests per second (the default)

Up to 50 per account; the 51st is refused with CONFLICT.

Request body (application/json)

Field	Type	Description
`name`required	string	-max 100 chars
`filters`required	object	-

Response 201

Field	Type	Description
`data`required	object	Same fields as AccountSavedSearch, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/account/saved-searches" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme",
  "filters": {}
}'

Run it here with a test key.

Delete a saved search

DELETE/api/v1/account/saved-searches/{id}

Access: API key. Scoped keys need account:write.
Rate limit: 100 requests per second (the default)

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List your favorite routes

GET/api/v1/account/favorites

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Only routes you can still see (public and active, your own, or privately granted).

Response 200

Field	Type	Description
`data`required	object[]	-
`favoriteId`requireddata[].favoriteId	string (uuid)	-
`favoritedAt`requireddata[].favoritedAt	string (date-time)	ISO-8601 timestamp (UTC)
`id`requireddata[].id	string (uuid)	The route id
`type`requireddata[].type	string	-One of `voice`, `sms`
`country`requireddata[].country	string	-
`destinationName`requireddata[].destinationName	string	The listing name as a buyer reads it: generated by the platform, never the seller's text, and ending in the listing reference (e.g. "Niger Mobile · Ref 7K2Q", "A-Z Voice · Premium · Full CLI · Ref 3MX9"). Your own listings keep the name you gave them.
`listingRef`data[].listingRef	string	Anonymous short reference of the listing (4 characters, e.g. "7K2Q"): stable for the life of the listing, unique enough to tell two same-named listings apart, and derived from the listing alone (it says nothing about the seller). Absent on your own listings.
`pricePerUnit`requireddata[].pricePerUnit	money	USD per minute (voice) or per message segment (SMS) USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata[].billingIncrement	string \| null	-
`status`requireddata[].status	string	-
`expectedAsr`requireddata[].expectedAsr	string \| null	Seller-stated ASR %, 2-decimal string
`expectedAcd`requireddata[].expectedAcd	string \| null	Seller-stated ACD in minutes, 2-decimal string
`dialerCompatible`requireddata[].dialerCompatible	boolean	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Add a route to your favorites

POST/api/v1/account/favorites

Access: API key. Scoped keys need account:write.
Rate limit: 100 requests per second (the default)

Idempotent: favoriting twice is not an error.

Request body (application/json)

Field	Type	Description
`routeId`required	string (uuid)	-

Response 201

Field	Type	Description
`data`required	object	-
`routeId`requireddata.routeId	string (uuid)	-
`favorited`requireddata.favorited	boolean	-One of `true`
`id`requireddata.id	string (uuid) \| null	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/account/favorites" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "routeId": "<routeId>"
}'

Run it here with a test key.

Remove a route from your favorites

DELETE/api/v1/account/favorites/{routeId}

Access: API key. Scoped keys need account:write.
Rate limit: 100 requests per second (the default)

Idempotent: removing a route that is not a favorite is not an error.

Parameters

Name	In	Type	Description
`routeId`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`routeId`requireddata.routeId	string (uuid)	-
`favorited`requireddata.favorited	boolean	-One of `false`

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List your dedicated IP addresses

GET/api/v1/account/ips

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Empty, with enabled: false, while dedicated IPs are not offered.

Response 200

Field	Type	Description
`data`required	object[]	-
`assignmentId`requireddata[].assignmentId	string (uuid)	-
`ipId`requireddata[].ipId	string (uuid)	-
`address`requireddata[].address	string	-
`role`requireddata[].role	string	ingress = where you send traffic; egress = where your calls leave fromOne of `ingress`, `egress`
`boundBox`requireddata[].boundBox	string \| null	-
`assignedAt`requireddata[].assignedAt	string (date-time)	ISO-8601 timestamp (UTC)
`hint`requireddata[].hint	string	Plain-English instruction for this address
`enabled`	boolean	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get your SIP interconnect details

GET/api/v1/account/ips/interconnect

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Everything needed to connect: where to send traffic, which addresses our calls leave from, and what is already authorised.

Response 200

Field	Type	Description
`data`required	object	-
`enabled`data.enabled	boolean	-
`myIngressIp`requireddata.myIngressIp	string \| null	-
`myEgressIp`requireddata.myEgressIp	string \| null	-
`egressPendingNetwork`data.egressPendingNetwork	boolean	-
`edgeIp`requireddata.edgeIp	string	The shared address to send SIP to when you hold no dedicated one
`egressIps`requireddata.egressIps	string[]	Addresses our calls leave from; whitelist these with your carriers
`rtpPortRange`requireddata.rtpPortRange	string	-
`sipPort`requireddata.sipPort	integer	-
`onPlatform`requireddata.onPlatform	boolean	-
`onPlatformSignals`requireddata.onPlatformSignals	object	-
`switchOperator`requireddata.onPlatformSignals.switchOperator	boolean	-
`marketplaceBuyer`requireddata.onPlatformSignals.marketplaceBuyer	boolean	-
`dialerUser`requireddata.onPlatformSignals.dialerUser	boolean	-
`autoAuthorized`requireddata.autoAuthorized	boolean	-
`manualWhitelistNeeded`requireddata.manualWhitelistNeeded	boolean	-
`authorizedIps`requireddata.authorizedIps	string[]	-
`poolAvailable`requireddata.poolAvailable	integer	-
`egressPoolAvailable`requireddata.egressPoolAvailable	integer	-
`egressAvailable`requireddata.egressAvailable	boolean	-
`sipUsername`requireddata.sipUsername	string \| null	-
`hasSipPassword`requireddata.hasSipPassword	boolean	-
`enabled`	boolean	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get your connectivity brief

GET/api/v1/account/ips/connectivity

Access: API key. Scoped keys need account:read.
Rate limit: 100 requests per second (the default)

Where to send traffic, what to whitelist and how you are recognised, including per-purchase destinations, in plain language.

Response 200

Field	Type	Description
`data`required	object	-
`dedicatedIpsEnabled`requireddata.dedicatedIpsEnabled	boolean	-
`myAddress`requireddata.myAddress	string \| null	-
`myAddressSummary`requireddata.myAddressSummary	string	-
`sendTo`requireddata.sendTo	string	Where to send your SIP traffic
`sendToPort`requireddata.sendToPort	integer	-
`sendToSummary`requireddata.sendToSummary	string	-
`egressMode`requireddata.egressMode	string	-One of `dedicated`, `shared`
`egressAddresses`requireddata.egressAddresses	string[]	-
`egressSummary`requireddata.egressSummary	string	-
`authMethods`requireddata.authMethods	string[]	-One of `ip`, `digest`
`authSummary`requireddata.authSummary	string	-
`authorizedSourceIps`requireddata.authorizedSourceIps	string[]	-
`purchasedRoutes`requireddata.purchasedRoutes	object[]	-
`purchaseId`requireddata.purchasedRoutes[].purchaseId	string (uuid)	-
`routeId`requireddata.purchasedRoutes[].routeId	string (uuid)	-
`routeName`requireddata.purchasedRoutes[].routeName	string \| null	-
`destination`requireddata.purchasedRoutes[].destination	string \| null	-
`type`requireddata.purchasedRoutes[].type	string	-
`status`requireddata.purchasedRoutes[].status	string	-
`sendTo`requireddata.purchasedRoutes[].sendTo	string	-
`sendToPort`requireddata.purchasedRoutes[].sendToPort	integer	-
`sipUsername`requireddata.purchasedRoutes[].sipUsername	string \| null	-
`rtpPortRange`requireddata.rtpPortRange	string	-
`codecs`requireddata.codecs	string[]	-
`autoAuthorized`requireddata.autoAuthorized	boolean	-
`manualWhitelistNeeded`requireddata.manualWhitelistNeeded	boolean	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Take a dedicated ingress IP

POST/api/v1/account/ips/activate

Access: API key. Scoped keys need account:write.
Rate limit: 100 requests per second (the default)
Moves money: Takes a dedicated IP address.

Idempotent: when you already hold one it is returned with created: false and nothing is charged. Answers 201 when a new address was assigned.

Response 200

Field	Type	Description
`data`required	object	-
`assignmentId`requireddata.assignmentId	string (uuid)	-
`ipId`requireddata.ipId	string (uuid)	-
`address`requireddata.address	string	-
`role`requireddata.role	string	ingress = where you send traffic; egress = where your calls leave fromOne of `ingress`, `egress`
`boundBox`requireddata.boundBox	string \| null	-
`assignedAt`requireddata.assignedAt	string (date-time)	ISO-8601 timestamp (UTC)
`hint`requireddata.hint	string	Plain-English instruction for this address
`created`requireddata.created	boolean	False when you already held one (idempotent replay)
`monthlyPriceUsd`requireddata.monthlyPriceUsd	number	Monthly premium in USD (a number)
`charged`requireddata.charged	number	USD booked by THIS call; 0 on a replay

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Take a dedicated egress IP

POST/api/v1/account/ips/activate-egress

Access: API key. Scoped keys need account:write.
Rate limit: 100 requests per second (the default)
Moves money: Takes a dedicated IP address.

Idempotent like the ingress version. Refused with VALIDATION_ERROR while dedicated sending addresses are not available.

Response 200

Field	Type	Description
`data`required	object	Same fields as AccountActivatedIp, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Release a dedicated IP

POST/api/v1/account/ips/{id}/release

Access: API key. Scoped keys need account:write.
Rate limit: 100 requests per second (the default)

Hands the address back to the pool. id is the assignment id or IP id from the list.

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`released`requireddata.released	boolean	-One of `true`
`address`requireddata.address	string	-
`ipId`requireddata.ipId	string (uuid)	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.