Manage your Photon messaging platform directly through AI agents. Create projects, configure messaging channels, send and read messages, manage contacts and phone numbers, track message activity, and monitor organization billing usage through Photon’s API.
Claude is Anthropic's AI assistant, available as a desktop app and in Cowork. It supports custom connectors, so it can call MCP servers directly from a chat.
This guide connects Photon MCP to Claude Desktop through MewCP, so Claude Desktop can use Photon MCP's 150 tools, like assignSmsLineCampaign, assignVoiceLineProfile and batchUpdateVoiceLineProfileAssignments, without your Photon MCP credentials ever reaching the app.
Photon MCP signs in through managed OAuth. MewCP stores the token encrypted, refreshes it before it expires and injects it only at call time. Your agent never holds it, so it can never leak it.
More apps
TinyFish MCP for running AI-driven browser automation tasks, deep web research, persistent browser login profiles, remote CDP browser sessions, and agentic wallet payments.
Manage Gmail end to end with tools for sending, reading, replying to and organizing emails. Work with threads, labels, drafts, attachments and inbox workflows while keeping communication and email automation in one place.
Microsoft Outlook MCP Server gives AI agents full control over Outlook email and calendar workflows, including reading and sending emails, managing attachments, organizing mail, scheduling and updating meetings, managing contacts, and creating tasks.
Connect to external APIs, webhooks and internet services through standard HTTP requests. Build integrations with virtually any platform that exposes a web-based interface.
Other clients
Photon MCP works the same way in every client below. Pick yours for its own guide.
Free to start.
Scope access to the exact Photon MCP tools and accounts you allow, work and personal side by side. Anything outside that scope is refused at call time, even when the model asks for it.
Each call is logged: what ran, on which account, and whether it worked. Failures come back structured, so the agent knows whether to retry instead of guessing.
Every app sits behind one secure MCP URL, and there is no server for you to deploy or keep running. Add an integration in the dashboard and it is live on the next call, with no config to change and no new credentials to wire up. Tools load only when a task needs them, so your agent stays fast and focused however many apps you connect.
In Claude, open Settings → Connectors, then choose Add custom connector.
Name it "mewcp" and paste the URL.
A browser window opens the first time the client connects. Sign in and approve access. No API key needed.
Start a new chat and ask: "List the tools you can use from MewCP." You should see your connected apps.
Assign or replace SMS line campaign Attach a ready campaign from this project’s organization to its line. Requires platforms:write for the project; human and machine actors retain their authenticated identity. Requires a permanent Idempotency-Key and the current assignment version. Provider provisioning runs asynchronously. If the operation fails, its `error` is the problem of one of these codes: `SMS_CAMPAIGN_PROVIDER_REJECTED`, `SMS_CAMPAIGN_RECONCILIATION_REQUIRED`, `SMS_CAMPAIGN_REVOKED`. API reference: https://photon.codes/docs/beta/api-reference/sms-campaigns/assign-or-replace-sms-line-campaign
Assign Voice line profile Assigns or replaces a line's explicit additional-profile override when the resource version matches. The current default cannot be assigned explicitly. The pstn_voice ability remains the admission source of truth. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/assign-voice-line-profile
Batch update Voice line assignments Atomically sets additional-profile overrides or switches lines back to the project default for up to 100 Voice-capable lines. A null profileId means use the default. Every expected resource version must match or no line changes. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/batch-update-voice-line-assignments
Cancel operation Withdraws a provision that has not been fulfilled yet. This is an operations action rather than a DELETE, because there is nothing to delete: no resource exists until the work commits. Whether it is accepted depends on the resource type — a dedicated iMessage line may sit waiting on inventory for hours and withdrawing costs nothing, while an SMS number is cancellable during inventory waiting and answers 409 once the workflow commits to its first provider order. Campaign assignment and detachment operations cannot be cancelled in any state. Wait for completion before requesting another change; that new change is not a guaranteed rollback. The output-only `cancellable` field is a snapshot; the cancellation transaction always checks the current phase under a row lock. A cancel that loses the race against the work finishing also answers 409: the resource exists and is billed for, so what you want then is to release it. Nothing is charged for a cancelled provision — billing runs after the work, so there is never anything to refund. Requires the platforms:write permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/operations/cancel-operation
Request a DMARC DNS check Reads stored DMARC policy diagnostics for a v2 Email domain. Checking queues a bounded DNS observation; it never edits DNS or changes sending permissions. Missing, malformed, multiple and unavailable are distinct. A valid record does not prove any individual message passes DMARC. p=none monitors only. Records may be inherited; existing policies must not be overwritten. Domain Connect is optional. API reference: https://photon.codes/docs/beta/api-reference/email-domains/request-a-dmarc-dns-check
Check project slug availability Reports whether createProject would accept `slug` right now. Advisory: only the create itself allocates, so a caller must still handle SLUG_TAKEN. A malformed slug is rejected on shape; a reserved slug, a slug held by an active project, and a slug retired with a deleted project each answer `available: false` with a reason. API reference: https://photon.codes/docs/beta/api-reference/projects/check-project-slug-availability
Commit profile picture Commits a profile picture previously uploaded through createAccountProfilePictureUpload. Call this only after the direct multipart upload succeeds, using the uploadId from the same upload session and a stable Idempotency-Key. The service validates the temporary object's ownership, size, content type, image bytes, dimensions, encryption, and age before changing the Account. API reference: https://photon.codes/docs/beta/api-reference/account/commit-profile-picture
Commit agent avatar Commits an agent avatar previously uploaded through createAgentProfileAvatarUpload. Call this only after the direct multipart upload succeeds, using the uploadId from the same upload session and a stable Idempotency-Key. The service validates the temporary object's Project ownership, size, content type, image bytes, dimensions, encryption, and age before changing the agent profile. API reference: https://photon.codes/docs/beta/api-reference/agent-profile/commit-agent-avatar
Commit iMessage contact profile picture Validates an uploaded picture and changes the custom profile picture when expectedVersion matches. Returns 200 after confirmation and commit, 202 while pending, or a problem on failure. Repeat the same request with the same Idempotency-Key after Retry-After to await the result; replay does not consume the upload again. Results are retained for 24 hours; key replay precedes version validation. A different change while one is pending returns 409. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/imessage/commit-imessage-contact-profile-picture
Connect email domain Reserves a normalized DNS domain and starts its durable email-provider setup. The accepted provision consumes one email-domain entitlement slot until it fails, is cancelled, or becomes a live resource; the plan's email.max_email_domains value sets the project limit. The customer resource does not exist until provider identity and DNS setup reach READY; poll the returned operation for progress. A domain may have only one unfinished provision or live resource globally. Email domains have no additional per-domain charge. The Idempotency-Key is required and permanent: replaying the same key and canonical domain returns the original operation forever. Requires the platforms:write permission bound to the project resource in the path. If the operation fails, its `error` is the problem of one of these codes: `EMAIL_DOMAIN_PROVIDER_REJECTED`, `EMAIL_DOMAIN_VERIFICATION_FAILED`, `EMAIL_DOMAIN_VERIFICATION_TIMED_OUT`, `EMAIL_TENANT_SETUP_TIMED_OUT`. API reference: https://photon.codes/docs/beta/api-reference/email-domains/connect-email-domain
Connect Telegram bot Starts a free managed Telegram bot connection. Each project may have one unfinished Telegram provision, including user interaction and failure cleanup. A different Idempotency-Key while one is active returns 409 TELEGRAM_PROVISION_IN_PROGRESS with its operationId and operationUrl; resume it, cancel it while cancellation is available, or wait for it to finish. Rejected keys remain reusable. Open detail.setupUrl to create a new bot, whose name and username are chosen in Telegram, or to connect an existing managed bot, then poll Location. The link remains usable while the operation is active and never expires. Replaying the same Idempotency-Key returns the original operation, even after completion or while a newer setup is active. POST, GET and list share the same operation details. The API includes detail.setupUrl only for callers with platforms:write for the project; read-only callers receive the other details unchanged. If the operation fails, its `error` is the problem of one of these codes: `TELEGRAM_CONFIGURATION_FAILED`. API reference: https://photon.codes/docs/beta/api-reference/telegram/connect-telegram-bot
Count filtered verification codes Counts the verification codes Photon kept from this project's dedicated lines, optionally for one `platform`. Without `receivedAfter` and `receivedBefore` the window is the 30 days before the request; a window longer than 366 days is rejected. The response echoes the window it resolved, so the number always says which period it covers. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/verification-codes/count-filtered-verification-codes
Count Messages Counts matching Messages before pagination. Delivery updates do not add Messages; results are eventually consistent. API reference: https://photon.codes/docs/beta/api-reference/messages/count-messages
Count projects Counts the projects the same filter would list. The count is read from the primary, so it is authoritative rather than replica-lagged. API reference: https://photon.codes/docs/beta/api-reference/projects/count-projects
Count a line's filtered verification codes Counts the verification codes Photon kept from one dedicated line. Without `receivedAfter` and `receivedBefore` the window is the 30 days before the request; a window longer than 366 days is rejected. The response echoes the window it resolved, so the number always says which period it covers. Answers 404 unless the project holds the resource now. Codes from an earlier tenure stay in the project-wide list. Filter by `platform` — a dedicated line receives both iMessage and WhatsApp. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/verification-codes/count-a-lines-filtered-verification-codes
Count Spaces Counts distinct Spaces matching the list filters; multiple matching Messages count once. Results are eventually consistent. API reference: https://photon.codes/docs/beta/api-reference/spaces/count-spaces
Count Users Counts distinct Users matching the list filters, including incoming senders or outgoing recipients selected by Message filters. Results are eventually consistent. API reference: https://photon.codes/docs/beta/api-reference/users/count-users
Create profile picture upload Creates a ten-minute, Account-bound presigned S3 POST for a JPEG, PNG, or WebP profile picture up to 5 MiB. Copy every returned formFields entry into a multipart/form-data request to uploadUrl, append the local file as the final form part, and upload it directly without sending Photon credentials. After the upload succeeds, call commitAccountProfilePicture with the returned uploadId. Do not cache or log the upload URL or form fields. API reference: https://photon.codes/docs/beta/api-reference/account/create-profile-picture-upload
Create agent avatar upload Creates a ten-minute, Project-bound presigned S3 POST for a JPEG, PNG, or WebP agent avatar up to 5 MiB. Copy every returned formFields entry into a multipart/form-data request to uploadUrl, append the local file as the final form part, and upload it directly without sending Photon credentials. After the upload succeeds, call commitAgentProfileAvatar with the returned uploadId. Do not cache or log the upload URL or form fields. API reference: https://photon.codes/docs/beta/api-reference/agent-profile/create-agent-avatar-upload
Create default Voice profile Creates the project default Voice profile when absent. An identical replay returns the existing default without changing its version; a different existing default conflicts. Direction configuration is managed separately. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/create-default-voice-profile
Create iMessage contact profile picture upload Creates a 10-minute presigned upload for a JPEG, PNG, or WebP profile picture of at most 5 MiB and 4096 pixels per side, bound to the line's active iMessage ability period. Works in every mode and changes nothing. Send the file as multipart/form-data to uploadUrl with every form field, without Photon credentials, then commit it with commitImessageContactProfilePicture. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/imessage/create-imessage-contact-profile-picture-upload
Create or get a Space Creates or returns a project Space. Idempotency-Key is required for every platform and binds the project, platform and initial User IDs (unordered except the iMessage creator in first position) for 24 hours after workflow completion. Concurrent matching requests join the same operation; conflicting reuse returns 422 once its outcome is available. A new email key creates a new thread; direct Spaces and SMS groups converge by participants. Every creation and successful replay requires at least one currently project-owned Agent, or for iMessage a shared-line Agent in a direct Space whose peer has an active Assignment of this project on that line. For iMessage, an existing exact match is reused; otherwise the first participant must be a project-owned dedicated phone Agent and creates the native direct chat or group. Multiple matching native groups return SPACE_AMBIGUOUS; incomplete group membership cannot establish an exact match. Replays return 200 and the current stored Space, with Idempotent-Replayed: true. A timeout does not cancel accepted work: retry the same key and input. API reference: https://photon.codes/docs/beta/api-reference/spaces/create-or-get-a-space
Create or get a User Creates or reconciles a User by normalized handle. WhatsApp and iMessage phone classification uses line allocation and project ownership; New iMessage email handles start as Human without lookup; existing email identities retain their producer-observed classification and ownership. WhatsApp Business uses project ownership. These three platforms perform no provider profile or enrichment fetch. Shared Agents expose type=shared without ownership IDs; dedicated Agents expose resourceId for this project or pairwise managedBy for another project. Dedicated lines without an active owner are unavailable. SMS retains its existing ownership and phone number enrichment behavior. Email retains domain ownership resolution, lowercase ASCII domains and case-preserved local parts. Dependency failures fail before classification writes. The natural identity is the project path ID, platform, and handle. Retrying after a committed creation whose response was lost returns the same User with 200 rather than replaying 201. API reference: https://photon.codes/docs/beta/api-reference/users/create-or-get-a-user
Create project Creates in the authorized organization. In addition to account credentials, explicitly granted Service Identity API keys and M2M tokens may create projects. Project API keys cannot create projects. Creator and private credential evidence come only from the trusted authorization context. The caller-selected slug is immutable, must be 3 to 63 lowercase ASCII alphanumerics separated by single hyphens, and cannot be reserved or held by any active or deleted project. API reference: https://photon.codes/docs/beta/api-reference/projects/create-project
Create shared line assignment Maps an end user's iMessage handle — an E.164 phone number or an email address — onto one of the project's pooled shared iMessage lines, consuming a seat from the project's entitlement. The assigned number is allocated by the server. When an email address is supplied in `email` the user is sent an invite asynchronously to that address; it is never inferred from the handle, and the response never reports whether the send succeeded. Requires the platforms:write permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/shared-line-assignments/create-shared-line-assignment
Register a brand Registers an encrypted US 10DLC brand. Registration is free, but it is refused with 402 before anything is created when the organization has no payment method on file, or has an invoice overdue 7 days or more or a disputed payment. Registration starts immediately and consumes one of the organization's rolling registration slots; deleting the brand later does not return the slot. The response is redacted; EIN and phone are write-only and represented only by their last four characters. Poll the URL in Location while status is submitting or submitted. API reference: https://photon.codes/docs/beta/api-reference/10dlc-brands/register-a-brand
Register a campaign Creates a campaign for an organization-owned brand, charges the non-refundable registration amount, and submits automatically after brand verification and qualification. The selected use cases are immutable after submission. Replay a pending request with the same body and Idempotency-Key. API reference: https://photon.codes/docs/beta/api-reference/10dlc-campaigns/register-a-campaign
Create Voice profile Creates a direction-neutral additional Voice profile. The project default must already exist. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/create-voice-profile
Create WhatsApp shared line assignment Maps an end user's phone number onto one of the project's pooled shared WhatsApp lines, consuming a seat from the project's WhatsApp entitlement. The assigned number is allocated by the server. When an email address is supplied the user is sent an invite asynchronously; the response never reports whether that succeeded. Requires the platforms:write permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/whatsapp-shared-line-assignments/create-whatsapp-shared-line-assignment
Create WhatsApp VoIP sender Registers an active, SMS-capable Photon VoIP line on this project's connected WhatsApp Business Account. The account is resolved server-side; callers never select a WABA. The platform creates or reuses the Meta number, requests and consumes the SMS ownership code internally, verifies it, and registers the sender. displayName is optional; when omitted the project agent profile name is snapshotted before acceptance. The VoIP line remains a separate resource and never receives the whatsapp_business ability. If the operation fails, its `error` is the problem of one of these codes: `WHATSAPP_AUTHORIZATION_REVOKED`, `WHATSAPP_DISPLAY_NAME_CONFLICT`, `WHATSAPP_NUMBER_ADD_REFUSED`, `WHATSAPP_NUMBER_LOOKUP_FAILED`, `WHATSAPP_REGISTRATION_REFUSED`, `WHATSAPP_VERIFICATION_REFUSED`, `WHATSAPP_VERIFICATION_REQUEST_REFUSED`, `WHATSAPP_VERIFICATION_TIMED_OUT`. API reference: https://photon.codes/docs/beta/api-reference/whatsapp-business/create-whatsapp-voip-sender
Delete account Deletes the authenticated account and returns its account tombstone. The operation is rejected while the account still owns organizations; transfer or close those organizations before retrying. This endpoint acts on the caller's account and does not accept another account's identifier. API reference: https://photon.codes/docs/beta/api-reference/account/delete-account
Delete project Starts deletion of the identified project using a credential authorized for project management. Inspect the documented response and use getProjectClosureStatus with the organization and project identifiers to read closure progress. A project API key is not an accepted credential for this operation. API reference: https://photon.codes/docs/beta/api-reference/projects/delete-project
Delete an unverified brand registration Deletes a brand whose registration was never verified: one in status otp_required or action_required that has no campaigns. The deletion is final once this returns; the brand is no longer listed, and every route addressing its ID returns BRAND_NOT_FOUND. A deleted brand still counts toward the organization's rolling registration limit. API reference: https://photon.codes/docs/beta/api-reference/10dlc-brands/delete-an-unverified-brand-registration
Delete Voice profile Deletes an additional profile when expectedVersion matches. Assigned profiles require force=true, which atomically removes every stored override so affected lines follow the default. The default can never be deleted. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/delete-voice-profile
Delete Voice inbound configuration Removes a profile's inbound destination when the shared profile version matches. The profileId may identify the default or an additional profile. The profile and its line assignments remain. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/delete-voice-inbound-configuration
Revoke Voice outbound credential Revokes outbound calling for a profile when the shared profile version matches. The profileId may identify the default or an additional profile. The profile, inbound destination, and line assignments remain. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/revoke-voice-outbound-credential
Delete webhook destination Deletes the selected project's destination and returns its stable tombstone. Repeated deletion returns the deletion representation. This operation removes the destination configuration; it is separate from disabling a destination through an update. API reference: https://photon.codes/docs/beta/api-reference/webhook-destinations/delete-webhook-destination
Disconnect WhatsApp Business account Disconnects every attached WhatsApp sender, then unsubscribes our app and removes the project's business account connection. Photon VoIP lines and the numbers in Meta remain. Requires Idempotency-Key. Poll the returned operation. Meta's answers do not fail it: each sender is released as `DELETE /platforms/resources/:resourceId` does, and our app's unsubscribe is a best effort, tried up to three times, a second or two apart, only while the failure is temporary. New signups are blocked while disconnecting, and existing provisions must finish before this request can be accepted. If the operation fails, its `error` is the problem of one of these codes: `WHATSAPP_ACCOUNT_DISCONNECT_FAILED`. API reference: https://photon.codes/docs/beta/api-reference/whatsapp-business/disconnect-whatsapp-business-account
Get account Returns the profile of the authenticated account. The account is selected from the credential rather than a request parameter. A missing or deleted account is reported as an error instead of an empty profile. API reference: https://photon.codes/docs/beta/api-reference/account/get-account
Get agent profile Returns the agent profile belonging to the identified project. The profile is project-scoped and is distinct from the authenticated account's personal profile. Use the dedicated avatar operations when uploading or removing an agent avatar. API reference: https://photon.codes/docs/beta/api-reference/agent-profile/get-agent-profile
Get attachment Returns an Attachment's metadata. Use the content endpoint to download its bytes. If its metadata is unavailable after ten seconds, returns ATTACHMENT_NOT_READY with Retry-After: 5. API reference: https://photon.codes/docs/beta/api-reference/attachments/get-attachment
Get billing operation Returns the authoritative state of a billing operation belonging to the selected project. Use it to recover or poll a plan-change request until the operation reaches success or failure. An accepted request is not evidence that the plan change has completed. API reference: https://photon.codes/docs/beta/api-reference/project-billing/get-billing-operation
Get project billing overview Returns the selected project's plan information, entitlements and current billing-period usage. This operation reads project billing state; it does not change plans or the payer's payment method. Organization-level plans are available through the organization billing overview. API reference: https://photon.codes/docs/beta/api-reference/project-billing/get-project-billing-overview
Read the credential's organization Reads the organization the credential is bound to: the organization an OAuth grant was consented for, or a Service Identity's own organization. Use it to discover which organization an integration acts for, and pass its organizationId to organization-scoped operations. API reference: https://photon.codes/docs/beta/api-reference/organizations/read-the-credentials-organization
Get default Voice profile Gets the profile currently selected as the project default, including its optional inbound delivery state. Requires platforms:read bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/get-default-voice-profile
Get the Developer OTel query schema Returns the logical tables and columns the advanced query endpoint can read, together with the supported SQL capabilities and request limits. Callers, especially agents, should read this schema instead of guessing column names. API reference: https://photon.codes/docs/beta/api-reference/developer-otel/get-the-developer-otel-query-schema
Get a Developer trace Returns the complete Project-visible stored OTLP trace without rewriting Span fields or attributes. API reference: https://photon.codes/docs/beta/api-reference/developer-otel/get-a-developer-trace
Get the project's effective billing terms Returns what the selected project is billed on now, per category it holds: the plan as its subscription has it, with any override applied, each fixed charge at the subscription's price and quantity, and resolved entitlements; where the plan comes from; how invoices are paid; the current period and next billing date; and any downgrade or cancellation waiting for the period end. Supply both organizationId and projectId; the organization must pay for the project. This operation does not change billing. API reference: https://photon.codes/docs/beta/api-reference/organization-billing/get-the-projects-effective-billing-terms
Get email delivery metrics Reads cached supplementary email series for the exact Project and rolling day or week. Coverage is eligible single-recipient messages; multi-recipient and simulator traffic is excluded. Observed complaints include reported feedback only. Missing data is distinct from zero. Original timestamps and availability are preserved; freshness describes retrieval, not complete event coverage. These series are not complete recipient totals, billing totals or Photon reputation rates. This read never queries the delivery provider or authorizes sending. Requires platforms:read for the path Project. API reference: https://photon.codes/docs/beta/api-reference/email/get-email-delivery-metrics
Get DMARC diagnostics Reads stored DMARC policy diagnostics for a v2 Email domain. Checking queues a bounded DNS observation; it never edits DNS or changes sending permissions. Missing, malformed, multiple and unavailable are distinct. A valid record does not prove any individual message passes DMARC. p=none monitors only. Records may be inherited; existing policies must not be overwritten. Domain Connect is optional. API reference: https://photon.codes/docs/beta/api-reference/email-domains/get-dmarc-diagnostics
Get email sending policies Reads Organization email recipient allowances shared across all its Projects, with rolling 60-second and 24-hour windows. Also returns Project and Organization review status and Photon policy pauses. Projects have no separate recipient quota. These limits are independent of subscription allowances. A policy pause blocks sending; an unpaused policy does not guarantee that every domain, suppression or account check permits a send. Requires platforms:read for the path Project. API reference: https://photon.codes/docs/beta/api-reference/email/get-email-sending-policies
Get iMessage line contact profile Reads the dedicated line's confirmed contact-profile configuration. Pending changes are not exposed. Project mode resolves the Projects agent identity; custom mode returns the line's own names and pictureUrl; none resolves to null. Requires platforms:read bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/imessage/get-imessage-line-contact-profile
Get iMessage profile sharing Reads whether the project's dedicated lines share their iMessage contact profile automatically. Off until set. Requires platforms:read bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/imessage/get-imessage-profile-sharing
Get a Message Returns one stored Message by canonical Photon Message ID on any supported contract platform. The globally unique Message ID is resolved within the authorized Project. Unsupported platform Messages are outside this collection and return MESSAGE_NOT_FOUND. API reference: https://photon.codes/docs/beta/api-reference/messages/get-a-message
Get metrics backfill status Returns historical metrics update progress. Completion reflects lastVerifiedAt; queries remain available during updates. API reference: https://photon.codes/docs/beta/api-reference/messaging-%26-voice-metrics/get-metrics-backfill-status
Get metrics SQL schema Returns the message_events and call_events SQL schema, supported queries, and limits for the selected API version. API reference: https://photon.codes/docs/beta/api-reference/messaging-%26-voice-metrics/get-metrics-sql-schema
Get operation Reads one operation using the same operation representation as creation and list. The API includes detail.setupUrl only with platforms:write for this project. This is the polling endpoint every asynchronous request here points its Location at, and it resolves from the moment that request is accepted — an operation is committed before its work is dispatched, so there is no window in which the URL 404s. Poll until `state` is one of `succeeded`, `failed` or `cancelled`, pacing from the Retry-After the accepting response returned. While an email domain waits for DNS, `detail` always contains the manual records and may additionally contain `automaticSetup` with a signed provider URL to open separately. Once the operation has produced a resource, the response carries that resource too, so the poll that finishes is also the one that tells you what you got. `succeeded` means the work is done; billing runs behind it and is not something the caller waits on. Operations are never purged, so a 404 means the id was never this project's. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/operations/get-operation
Get organization billing overview Returns the selected organization’s billing subscription and entitlementsVersion. The subscription can be null. Read the returned plan, charges and entitlements to inspect organization billing; this operation does not purchase or change a plan. API reference: https://photon.codes/docs/beta/api-reference/organization-billing/get-organization-billing-overview
Get organization credit Returns the credit the selected organization holds: on credit notes, such as the unused time of a plan an upgrade replaced or the unused days of a prorated fixed charge it released, and in its wallet: the credit Photon granted it, such as a new account's first organization's welcome credit, and any prepaid credit it bought. It offsets that organization's invoices of any kind except one-off invoices, credit notes first. Reading it does not apply or change credit. API reference: https://photon.codes/docs/beta/api-reference/organization-billing/get-organization-credit
Get organization payment method Reports whether the selected organization has a card on file, its documented payment-method metadata, whether a purchase needs a card first (purchaseRefusal), and how it pays: by card, or by invoice on its contract's terms (agreement). Reading this endpoint does not collect a new card or create a checkout session. API reference: https://photon.codes/docs/beta/api-reference/organization-billing/get-organization-payment-method
Get the organization's effective billing terms Returns what the selected organization is billed on now on its own subscription, such as SSO and 10DLC campaigns: the plan as the subscription has it, with any override applied, each fixed charge at the subscription's price and the quantity the organization holds, and resolved entitlements; where the plan comes from; how invoices are paid; the current period and next billing date; and any downgrade or cancellation waiting for the period end. subscription has a project subscription's terms without its category, and is null when the organization holds none. Project subscriptions are read per project. This operation does not change billing. API reference: https://photon.codes/docs/beta/api-reference/organization-billing/get-the-organizations-effective-billing-terms
Get project Returns the identified project's settings for an authorized caller. The credential must be allowed to access that project; possession of an unrelated project's key does not provide access. Missing and deleted projects are reported through the documented error responses. API reference: https://photon.codes/docs/beta/api-reference/projects/get-project
Get project closure status Returns closure progress for projectId within organizationId, including deletionOperationId, domain progress and ready. This read operation does not initiate deletion. API reference: https://photon.codes/docs/beta/api-reference/projects/get-project-closure-status
Get project iMessage platform Reports whether the project is on shared or dedicated iMessage lines, derived from its billing entitlements. Shared mode carries the seat cap. Both say whether a dedicated line requested now would be assigned without waiting. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/platforms/get-project-imessage-platform
Get project WhatsApp platform Reports whether the project is on shared or dedicated WhatsApp lines, derived from its billing entitlements. Shared mode carries the seat cap. Both say whether a dedicated line requested now would be assigned without waiting. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/platforms/get-project-whatsapp-platform
Get resource Reads one resource the project holds. A released number stays readable and reads `retired`, because it remains part of this project's history. A dedicated line given back does NOT: returning it to inventory is what makes it claimable by someone else, so it answers 404 and the operation that returned it is the record that this project once held it. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/resources/get-resource
Get shared line assignment Reads one shared line assignment. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/shared-line-assignments/get-shared-line-assignment
Get SMS line campaign assignment Read the last confirmed campaign and current eligibility. Follow changes through their operations. Eligibility is a control-plane assessment, not a delivery or recipient-consent guarantee. API reference: https://photon.codes/docs/beta/api-reference/sms-campaigns/get-sms-line-campaign-assignment
Get a Space Returns one stored Space by canonical Photon Space ID. A Space of a kind its platform does not support returns OPERATION_UNAVAILABLE. API reference: https://photon.codes/docs/beta/api-reference/spaces/get-a-space
Get a redacted brand Returns the redacted registration record for brandId within the selected organization. Use this representation to inspect registration state; it does not return every sensitive field originally submitted when the brand was registered. Supply organization_id for the organization that owns the registration. API reference: https://photon.codes/docs/beta/api-reference/10dlc-brands/get-a-redacted-brand
Get sole-proprietor OTP status Returns the redacted one-time-password verification state for an organization-owned brand. OTP verification applies only to sole-proprietor brands. Reading this endpoint does not request another code or verify a supplied code; use the trigger and verification operations for those actions. Supply organization_id for the organization that owns the registration. API reference: https://photon.codes/docs/beta/api-reference/10dlc-brand-otp/get-sole-proprietor-otp-status
Get a campaign Returns the registration record and current state of campaignId within the selected organization. This is the read operation for observing a campaign after registration or correction; a successful read does not itself indicate that registration has been approved. Supply organization_id for the organization that owns the registration. API reference: https://photon.codes/docs/beta/api-reference/10dlc-campaigns/get-a-campaign
Get campaign fees Returns what registering a campaign bills the selected organization: the non-refundable registration fee, charged again on every resubmission, and the monthly fee each campaign bills from carrier approval. Amounts are list prices read from billing; tax is not included. Show them before creating or resubmitting a campaign. API reference: https://photon.codes/docs/beta/api-reference/10dlc-campaigns/get-campaign-fees
Get an User Returns one User after refreshing its Human or Agent classification and project ownership where supported. iMessage email identities retain their producer-observed classification and ownership because no current email ownership lookup is available. WhatsApp, WhatsApp Business and iMessage perform no provider fetch; only SMS Human classifications perform a phone number lookup. Current-project Agents expose resourceId; external-project Agents expose only pairwise managedBy. Conditional response evaluation uses the post-reconciliation representation. Stored reads use each platform definition; projection requires adapter support. API reference: https://photon.codes/docs/beta/api-reference/users/get-an-user
Get Voice line profile assignment Gets the explicit additional-profile override for an owned Voice-capable line. A line following the project default returns 200 without profileId. Requires platforms:read bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/get-voice-line-profile-assignment
Get Voice profile Gets one reusable Voice profile, including its optional inbound delivery state. Requires platforms:read bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/get-voice-profile
Get webhook destination Returns the configuration of one webhook destination belonging to the selected project. Missing or deleted destinations are reported as errors. This read does not disclose the signing secret returned when the destination or a secret rotation was created. API reference: https://photon.codes/docs/beta/api-reference/webhook-destinations/get-webhook-destination
Get webhook event schema Returns the published reader JSON Schema for eventType in the requested webhook apiVersion. Use it to interpret events for that exact payload version. The response media type is application/schema+json; an authorized conditional request may return 304 without a body. Unsupported event/version combinations are rejected. API reference: https://photon.codes/docs/beta/api-reference/webhook-event-catalog/get-webhook-event-schema
Get WhatsApp Business account Gets the one WhatsApp Business Account this project has connected, with its number of live senders. Senders are resources and are listed by GET /platforms/resources?ability=whatsapp_business. The account is not a resource and carries no access token. Meta's retained numbers are listed separately by GET /platforms/whatsapp-business/account/phone-numbers. `subscribedAt` is absent until our app is attached to the account's webhooks. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/whatsapp-business/get-whatsapp-business-account
Get WhatsApp shared line assignment Reads one WhatsApp shared line assignment. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/whatsapp-shared-line-assignments/get-whatsapp-shared-line-assignment
Leave an organization; Owners must transfer or close first Removes the authenticated account's own membership. Nothing is revoked: the account's sessions, OAuth grants and Account Service Keys stop being accepted for the organization and its projects shortly after the call, and project API keys and Service Identity credentials it created keep working until they are revoked. Any member except the Owner can call it, with account credentials or an OAuth grant for this organization with the organization:read scope; the Owner gets 409 and must transfer ownership or delete the organization first. Send the caller's own membership version as expectedVersion, because a stale version returns 409, and supply the required Idempotency-Key header. API reference: https://photon.codes/docs/beta/api-reference/organization-members/leave-an-organization%3B-owners-must-transfer-or-close-first
List Account Service Keys Returns metadata for the authenticated account's unrevoked service keys, including expired keys, ordered newest first. Secret values are not returned; a key's credential is disclosed only when that key is created. API reference: https://photon.codes/docs/beta/api-reference/account-service-keys/list-account-service-keys
List attachments Lists the Project's Attachment metadata, with optional time filters. An Attachment can be absent until its upload finishes, which advances its updatedAt; follow changes with updatedSince. API reference: https://photon.codes/docs/beta/api-reference/attachments/list-attachments
List billing plans Lists the billing plan catalog, grouped by their public plan-metadata type. Use the returned plan information when choosing the category and planCode for a plan change. The catalog is the same for every project, and reading it does not purchase a plan. API reference: https://photon.codes/docs/beta/api-reference/project-billing/list-billing-plans
List credit activity Returns one page of how the selected organization's credit balance changed, newest first: credit notes issued and credit granted, credit applied to invoices, credit restored when the change an invoice paid for never applied, and credit voided. Each entry names the credit note (none for granted credit), the invoice when there is one, and the charge and subscription the credit note credits, or that the credit was a grant. Pass nextPage as page to read further. This operation does not change billing. API reference: https://photon.codes/docs/beta/api-reference/organization-billing/list-credit-activity
List Developer OTel log records Returns Project-visible Developer LogRecords in Timestamp, TraceId, SpanId descending order. The from/to range uses RFC 3339 timestamps at millisecond precision. Keep the range and filters fixed while incrementing offset; no total or page token is calculated. API reference: https://photon.codes/docs/beta/api-reference/developer-otel/list-developer-otel-log-records
List Developer traces Returns root Span summaries in Timestamp and TraceId descending order. The from/to range uses RFC 3339 timestamps at millisecond precision. Keep the range and filters fixed while incrementing offset; no total or page token is calculated. API reference: https://photon.codes/docs/beta/api-reference/developer-otel/list-developer-traces
List email recommendations Reads Photon guidance from stored sending policies, sending setup and domain checks. Project and Organization restrictions repeat on each page of domain observations. Follow nextPageToken until hasMore is false; observations describe only the current page. Recommendations are advisory reads, never permission to send or resume. Reputation-rate guidance and supplementary delivery advice are explicitly unavailable until their sources are integrated. An empty list does not indicate healthy reputation or resolved findings. Requires platforms:read for the path Project. API reference: https://photon.codes/docs/beta/api-reference/email/list-email-recommendations
List filtered verification codes Lists the verification codes Photon kept from this project's dedicated lines. Inbound messages that carry a one-time code are filtered before delivery; this is the record that they arrived, so a quiet line can be told apart from a broken one. It records the receiving line, its platform and when the code arrived — never the code itself. Each entry names the dedicated line (`resourceId`) that received it. Newest first, within an optional inclusive `receivedAfter`/`receivedBefore` window. A page may hold fewer than `pageSize` entries and still return a `nextPageToken`; only its absence means the end. Filter by `platform`; to read one line, use its own filtered-otp path. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/verification-codes/list-filtered-verification-codes
List invoices Returns one page of the selected organization's invoices, newest first: every invoice issued to it with a nonzero total or actual charges, including charges fully paid by credit; drafts and empty invoices are excluded. Each names what it charged the organization's own subscription and each project. Pass subject to list only the invoices that charge the organization itself or one of its projects, and nextCursor as cursor to read further. Listing invoices does not make a payment or modify a subscription. API reference: https://photon.codes/docs/beta/api-reference/organization-billing/list-invoices
List Messages Lists the Project's Messages, with optional resource, conversation, and time filters. Results are eventually consistent. API reference: https://photon.codes/docs/beta/api-reference/messages/list-messages
List number area codes Lists current provider coverage for US local numbers, sorted and deduplicated. Coverage does not guarantee inventory carrying every required feature. New area-specific purchases must use a listed code; accepted purchases keep waiting if coverage later changes. Requires platforms:read for the path project. API reference: https://photon.codes/docs/beta/api-reference/sms-numbers/list-number-area-codes
List number countries Lists supported purchase countries independently of current provider inventory. Requires platforms:read for the path project. API reference: https://photon.codes/docs/beta/api-reference/sms-numbers/list-number-countries
List operations Lists the project's operations using the same operation representation as creation and GET. The API includes detail.setupUrl only with platforms:write for this project. Results are oldest first — every provision and release it has ever asked for, including the ones still running. This is the entire in-flight view: a resource only appears once it is real, so nothing half-built shows up in the resource list and nothing in flight is missing from this one. Filter by `resourceId` to get one resource's whole history, which for a pooled line is every tenure this project has had on it. `state` is comma-separated; `type` accepts one operation type and an absent filter means everything, including failed and cancelled operations. `endedAfter` keeps only operations that finished after that instant, so what failed or was withdrawn recently is one short page. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/operations/list-operations
List current organization members Lists the organization's active members, ordered by account ID, with each member's role, membership version and account profile (name, email and picture); a member whose account is missing or deleted has a null profile. Any member can call it with account credentials, or with an OAuth grant for this organization that has the organization:read scope. The list is not paginated. API reference: https://photon.codes/docs/beta/api-reference/organization-members/list-current-organization-members
List payments to confirm Returns the selected organization's payments waiting on the customer's authentication (3DS), newest first, with what each pays for: a pending plan change, fixed-charge increase or one-off invoice, or an invoice such as a renewal. A plan change is not invoiced until it is paid, so its payment has no invoice number yet. Pass subject to list only the payments for the organization itself or one of its projects. Pay an invoice to complete its payment; listing makes no payment. API reference: https://photon.codes/docs/beta/api-reference/organization-billing/list-payments-to-confirm
List project platforms Lists the platform types available to this project. Every project currently sees the same fixed public contract, answered in-process rather than forwarded, so the list survives an outage of the private service. The project binding exists so that answer can narrow per project without moving the route. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/platforms/list-project-platforms
List project subscriptions Lists the plan each of the selected project's categories holds, with its price and the payer's standing. It suits showing a project's plan wherever projects are listed; the billing overview adds billing periods, fixed charges, entitlements and usage. API reference: https://photon.codes/docs/beta/api-reference/project-billing/list-project-subscriptions
List projects Returns a cursor-paginated page of the active projects in organizationId. Filter using query and the documented creation-time bounds, and navigate with pageSize and pageToken. Project roles are not returned and role is not a supported filter. API reference: https://photon.codes/docs/beta/api-reference/projects/list-projects
List a line's filtered verification codes Lists the verification codes Photon kept from one dedicated line. Inbound messages that carry a one-time code are filtered before delivery; this is the record that they arrived, so a quiet line can be told apart from a broken one. It records the receiving line, its platform and when the code arrived — never the code itself. Each entry names the dedicated line (`resourceId`) that received it. Newest first, within an optional inclusive `receivedAfter`/`receivedBefore` window. A page may hold fewer than `pageSize` entries and still return a `nextPageToken`; only its absence means the end. Answers 404 unless the project holds the resource now. Codes from an earlier tenure stay in the project-wide list. Filter by `platform` — a dedicated line receives both iMessage and WhatsApp. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/verification-codes/list-a-lines-filtered-verification-codes
List resources Lists the project's resources, oldest first, including retired ones unless `state` filters them out. Filter by `type`, by enabled `ability` and by comma-separated `state`. Lifecycle states are unallocated, active and retired; active means owned and non-retired, not provider-confirmed readiness. Every VoIP resource includes detail.activationState: activating or active, defaulting to active without owner-matched saved state. state=active includes numbers still activating. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/resources/list-resources
List shared line assignments Lists the project's shared line assignments, oldest first. Released assignments are excluded unless includeReleased is set. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/shared-line-assignments/list-shared-line-assignments
List Spaces Lists the Project's stored Spaces, with optional participant and Message filters. Results are eventually consistent. API reference: https://photon.codes/docs/beta/api-reference/spaces/list-spaces
List brands Lists the selected organization's 10DLC brands as a cursor-paginated page. Use status to filter the result and pageSize and pageToken to navigate it. Entries use a brand summary representation (identifier, display name, profile type, entity type when present, status and timestamps) rather than the full redacted brand; use getTenDlcBrand to read a brand's redacted registration details. Supply organization_id for the organization that owns the registration. API reference: https://photon.codes/docs/beta/api-reference/10dlc-brands/list-brands
List campaign review history Returns observed review-state changes for an organization-owned campaign, ordered newest first. Navigate the result with pageSize and pageToken. The history records changes already observed by Photon; it does not initiate a new review or resubmit the campaign. Supply organization_id for the organization that owns the registration. API reference: https://photon.codes/docs/beta/api-reference/10dlc-campaigns/list-campaign-review-history
List campaign use cases Returns the selectable messaging purposes and the allowed selection count. Campaign registration types are derived automatically from the brand profile and selected purposes. API reference: https://photon.codes/docs/beta/api-reference/10dlc-campaigns/list-campaign-use-cases
List campaigns Lists 10DLC campaigns visible within the selected organization. Filter by brandId, status or useCases and navigate the cursor-paginated result using cursor and limit. The result describes campaign registration state; listing a campaign does not submit or modify it. Supply organization_id for the organization that owns the registration. API reference: https://photon.codes/docs/beta/api-reference/10dlc-campaigns/list-campaigns
List Users Lists stored Users without refreshing their classification; use Get User for current details. Message filters select incoming senders or outgoing recipients, excluding the Message's own endpoint. API reference: https://photon.codes/docs/beta/api-reference/users/list-users
List Voice profiles Lists reusable Voice profiles in this project. Requires platforms:read bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/list-voice-profiles
List webhook API versions Lists the published webhook payload API versions and their lifecycle metadata. The list is the same for every project. Use the selectable indicator when choosing a version for a destination. These payload dates are separate from SDK package versions. An authorized conditional request may return 304 without a response body. API reference: https://photon.codes/docs/beta/api-reference/webhook-event-catalog/list-webhook-api-versions
List webhook destinations Returns a cursor-paginated page of active webhook destinations configured for the selected project. Use pageSize and pageToken to navigate it. The listing returns destination configuration, never signing secrets. API reference: https://photon.codes/docs/beta/api-reference/webhook-destinations/list-webhook-destinations
List webhook egress addresses Returns the public network addresses from which this environment sends webhook deliveries. Use this information when configuring the receiving system's network allowlist. The result is environment-specific and does not describe the API service's ingress addresses. API reference: https://photon.codes/docs/beta/api-reference/webhook-delivery/list-webhook-egress-addresses
List webhook event types Lists the webhook event types available in the requested apiVersion, including their descriptions, audiences and reader-schema URLs. Use this versioned catalog when selecting a destination's enabledEvents. The response may include version-retirement information; an authorized conditional request can return 304 without a body. API reference: https://photon.codes/docs/beta/api-reference/webhook-event-catalog/list-webhook-event-types
List WhatsApp account phone numbers Lists the connected WABA's phone numbers directly from Meta, including numbers whose Photon sender was disconnected. Ownership is photon for a number in this project's current Photon inventory and meta otherwise. Match a Photon SMS number by its E.164 phoneNumber and reuse its existing displayName when reconnecting. A null name is unavailable, not permission to choose a new name. A failed lookup returns an error rather than an empty list. Requires platforms:read on the path project. API reference: https://photon.codes/docs/beta/api-reference/whatsapp-business/list-whatsapp-account-phone-numbers
List WhatsApp shared line assignments Lists the project's WhatsApp shared line assignments, oldest first. Released assignments are excluded unless includeReleased is set. Requires the platforms:read permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/whatsapp-shared-line-assignments/list-whatsapp-shared-line-assignments
Mark a Message as read Persists a request to mark one incoming Message as read using its receiving account. A 202 means accepted for asynchronous execution, not handled by the provider. Requires Idempotency-Key. The returned action Message tracks its outcome; privacy settings may suppress remote visibility. API reference: https://photon.codes/docs/beta/api-reference/messages/mark-a-message-as-read
Preview an organization billing change Previews a fixed-charge quantity change on the selected organization's own subscription, such as SSO. Prices the change by the billing engine exactly as making it would bill it now: dueNow is that invoice, with taxes and the payer's credits applied. A purchase bills each unit it adds, even after a release this period. A release bills nothing; releasing a prorated charge credits its unused days to the organization's credit. dueLater is what the change leads to that is billed later instead, upcomingInvoices what the subscription it leaves bills in the following periods, and nextCharge the first of them. change says what the change does by its kind: for a fixed-charge change, pass change.quote on with the purchase so it is refused if the price or period no longer hold. This operation does not change billing. promotionCode previews a code as the purchase redeems it, and needs billing:manage; a refused code answers PROMOTION_CODE_REJECTED with the reason a refused purchase gives. API reference: https://photon.codes/docs/beta/api-reference/organization-billing/preview-an-organization-billing-change
Preview a project billing change Previews a change on the selected project's subscription in the supplied category: a fixed-charge quantity change, or a plan change with the held fixed charges it carries over. Prices the change by the billing engine exactly as making it would bill it now: dueNow is that invoice, with taxes and the payer's credits applied. A purchase bills each unit it adds, even after a release this period. A release bills nothing; releasing a prorated charge credits its unused days to the organization's credit. dueLater is what the change leads to that is billed later instead, upcomingInvoices what the subscription it leaves bills in the following periods, and nextCharge the first of them. change says what the change does by its kind: for a fixed-charge change, pass change.quote on with the purchase so it is refused if the price or period no longer hold. This operation does not change billing. An upgrade bills the replaced plan's usage to date and the new plan from now, less the replaced plan's unused time; a downgrade, or choosing the held plan again, bills nothing now; change says when it applies and which held fixed charges the target does not sell: released first for a change that applies now, released with a downgrade when it applies. additions quotes what is added once an upgrade applies, each billed when it is added, in dueLater and outside dueNow. promotionCode previews a code as the purchase redeems it, and needs billing:manage; a refused code answers PROMOTION_CODE_REJECTED with the reason a refused purchase gives. Supply both organizationId and projectId; the organization must pay for the project. API reference: https://photon.codes/docs/beta/api-reference/organization-billing/preview-a-project-billing-change
Provision dedicated iMessage line Claims one dedicated iMessage line for the project and enables iMessage on it. Always answers 202 with an operation: dedicated lines are allocated from available capacity, and unavailable capacity causes a wait rather than a failure — this can legitimately stay `running` for hours, which is exactly why the response is a handle to poll rather than a number. The project's messaging subscription must grant the dedicated iMessage lines entitlement (`imessage_dedicated_lines.can_purchase`), and that is checked before capacity is reserved. The line's own charge starts when a line is claimed; the subscription that grants the entitlement bills on its own terms, which cancelling a request does not change. Waiting requests are served first come, first served. One that is still waiting is cancelled with a `reason` if the project is deleted (`project_deleted`) or its plan stops selling dedicated lines (`entitlement_lost`); while the payer is restricted for overdue payment it keeps waiting. If you no longer want to wait, POST to the operation's cancel endpoint, which charges nothing for the line. The Idempotency-Key is required and permanent: repeating it returns the same operation forever. A further line always needs a NEW key, including while others are still waiting. An optional promotionCode is checked and claimed here, before the request waits for a line: a code that can't be used answers 409 PROMOTION_CODE_REJECTED and starts nothing. Requires the platforms:write permission bound to the project resource in the path. If the operation fails, its `error` is the problem of one of these codes: `CHARGE_REFUSED`, `ENTERPRISE_PLAN_REQUIRED`. API reference: https://photon.codes/docs/beta/api-reference/dedicated-imessage-lines/provision-dedicated-imessage-line
Provision dedicated WhatsApp line Provisions one dedicated WhatsApp line with WhatsApp and shared Voice enabled. It attaches to an eligible iMessage line the project already owns when possible so both products keep the same number; otherwise it claims healthy, available WhatsApp-capable dedicated-line inventory. Always answers 202, because waiting when no inventory is available is not a failure. The product opens its own charge period after the abilities are enabled; Voice has no separate charge. Waiting requests are served first come, first served, and are cancelled with a `reason` exactly as for a dedicated iMessage line. Cancel the returned operation to stop waiting. An optional promotionCode is checked and claimed here, before the request waits for a line: a code that can't be used answers 409 PROMOTION_CODE_REJECTED and starts nothing. The Idempotency-Key is required and permanent. If the operation fails, its `error` is the problem of one of these codes: `CHARGE_REFUSED`, `ENTERPRISE_PLAN_REQUIRED`. API reference: https://photon.codes/docs/beta/api-reference/dedicated-whatsapp-lines/provision-dedicated-whatsapp-line
Purchase SMS number Buys one US local number from the provider and records it as a resource with SMS enabled. Requires countryCode (US) and accepts an optional three-digit geographic areaCode. The server selects an exact matching number. While inventory is empty the operation keeps searching, and the caller can cancel it until ordering begins; a search still empty one minute after the operation was created fails it with `NUMBER_INVENTORY_UNAVAILABLE`. Always answers 202 with an operation: the work runs behind the response, and the Location points at the operation to poll. New area-specific requests must appear in current provider coverage; discover it with GET /sms/numbers/area-codes?countryCode=US. Coverage and subscription checks run before operation creation. Billing follows delivery. Replays return the original operation without checking current coverage. The Idempotency-Key is required and permanent: repeating it returns the same operation forever, never a second number. A further number always needs a NEW key, including while others are still running. An optional promotionCode is redeemed with the number's charge, which follows delivery: a code billing refuses hands the number back, and its release operation carries the refusal (`reason` `charge_refused`, with `detail.chargeRefusal` `{ code: "promotion_code_rejected", detail: <why> }`). Requires the platforms:write permission bound to the project resource in the path. If the operation fails, its `error` is the problem of one of these codes: `ENTITLEMENT_REQUIRED`, `NUMBER_INVENTORY_UNAVAILABLE`, `NUMBER_ORDER_FAILED`, `NUMBER_ORDER_RECONCILIATION_REQUIRED`, `NUMBER_SEARCH_FAILED`. API reference: https://photon.codes/docs/beta/api-reference/sms-numbers/purchase-sms-number
Query Developer OTel data Executes one parameterized, read-only ClickHouse SELECT statement against the current Project's otel_logs and otel_traces data. Supports non-recursive CTEs, subqueries, and JOINs; UNION and SELECT without FROM remain disabled, as do GLOBAL, ASOF, and PASTE JOIN. Every source is subject to the authorized Project's Row Policies. This advanced endpoint supplements the basic resource endpoints. API reference: https://photon.codes/docs/beta/api-reference/developer-otel/query-developer-otel-data
Query metrics Runs read-only SQL over the Project's message_events or call_events table. Get the SQL schema for supported columns, capabilities, and limits. API reference: https://photon.codes/docs/beta/api-reference/messaging-%26-voice-metrics/query-metrics
Release dedicated iMessage line Removes only iMessage from one dedicated line. Shared Voice is removed only when WhatsApp is absent; if WhatsApp remains, Voice, the resource, ownership, and phone number are preserved. Usually finishes inside this request and answers 200; a slow workflow answers 202 with an operation to poll. Takes no Idempotency-Key because the open iMessage charge period identifies this product tenure. If the operation fails, its `error` is the problem of one of these codes: `RESOURCE_NOT_FOUND`. API reference: https://photon.codes/docs/beta/api-reference/dedicated-imessage-lines/release-dedicated-imessage-line
Release resource Gives one resource back, whatever it is. What that means is the resource's own business: an SMS number goes back to the provider and is retired, a dedicated iMessage line goes back to the shared pool and stays in existence for someone else to claim. Either way the provider is contacted first where there is one, then a single transaction disables every ability, ends the project's hold and closes the charge period — so a provider that refuses leaves the resource exactly as it was, still owned and still billed. A WhatsApp Business sender is the exception: Meta never holds its release. A number on a Photon VoIP line is deregistered as a best effort, tried up to three times, a second or two apart, only while the failure is temporary; a number the customer brought is not sent to Meta at all; the sender is retired either way, and the number stays in the customer's WhatsApp Business Account. Usually finishes inside this request and answers 200; if the provider is slow it answers 202 and the Location points at the operation to poll. The decrement runs behind the answer either way, so the resource is gone when you are told it is. Takes no Idempotency-Key — releasing the same resource twice is the same request. Releasing one that is already gone answers 404. Requires the platforms:write permission bound to the project resource in the path. If the operation fails, its `error` is the problem of one of these codes: `EMAIL_DOMAIN_RELEASE_FAILED`, `NUMBER_RELEASE_FAILED`, `RESOURCE_NOT_FOUND`, `TELEGRAM_RELEASE_FAILED`, `WHATSAPP_SENDER_RELEASE_FAILED`. API reference: https://photon.codes/docs/beta/api-reference/resources/release-resource
Release shared line assignment Releases a shared line assignment, freeing both its seat and its handle for reassignment. The row is retained for audit and returned with releasedAt set, so repeating the call is safe. Requires the platforms:write permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/shared-line-assignments/release-shared-line-assignment
Release dedicated WhatsApp line Removes only WhatsApp from one dedicated line. Shared Voice is removed only when iMessage is absent; if iMessage remains, Voice, the resource, ownership, and phone number are preserved. Usually finishes inside this request and answers 200; a slow workflow answers 202 with an operation to poll. Takes no Idempotency-Key because the open WhatsApp charge period identifies this product tenure. If the operation fails, its `error` is the problem of one of these codes: `RESOURCE_NOT_FOUND`. API reference: https://photon.codes/docs/beta/api-reference/dedicated-whatsapp-lines/release-dedicated-whatsapp-line
Release WhatsApp shared line assignment Releases a WhatsApp shared line assignment, freeing its seat for reassignment. The row is retained for audit and returned with releasedAt set, so repeating the call is safe. Requires the platforms:write permission bound to the project resource in the path. API reference: https://photon.codes/docs/beta/api-reference/whatsapp-shared-line-assignments/release-whatsapp-shared-line-assignment
Remove iMessage contact profile picture Removes the custom profile picture and keeps the names when expectedVersion matches. An identical configuration keeps its version after verification. Returns 200 after confirmation and commit, 202 while pending, or a problem on failure. Repeat the same request with the same Idempotency-Key after Retry-After to await the result. Results are retained for 24 hours; key replay precedes version validation. A different change while one is pending returns 409. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/imessage/remove-imessage-contact-profile-picture
Remove profile picture Removes the authenticated account's custom profile picture and returns the account using its default picture. This operation does not upload a replacement; use the upload-and-commit operations when setting a new custom picture. Supply the required Idempotency-Key header. API reference: https://photon.codes/docs/beta/api-reference/account/remove-profile-picture
Reset agent avatar Replaces the selected project's agent avatar with the project's default avatar, a generated planet image derived from the project ID, and returns the updated agent profile. The reset does not restore an earlier avatar: a custom avatar it replaces is discarded and must be uploaded and committed again to use it. When the default avatar is already in use, the profile is returned unchanged. This does not change the account's personal profile picture. Supply the required Idempotency-Key header. API reference: https://photon.codes/docs/beta/api-reference/agent-profile/reset-agent-avatar
Resubmit a rejected campaign Resubmits saved campaign corrections, with an optional appeal explanation. An explanation is required when content has not changed. Each accepted resubmission incurs the existing non-refundable registration amount. Replay pending requests with the same body and Idempotency-Key. API reference: https://photon.codes/docs/beta/api-reference/10dlc-campaigns/resubmit-a-rejected-campaign
Revoke Account Service Key Revokes the account-owned service key identified by serviceKeyId and returns its revoked metadata. Repeating the revocation is stable. Revocation changes the credential's validity; it does not create a replacement key. Supply the required Idempotency-Key header. API reference: https://photon.codes/docs/beta/api-reference/account-service-keys/revoke-account-service-key
Send a Message Sends SMS, email, WhatsApp Personal, WhatsApp Business, iMessage, or Telegram text and image messages. A shared iMessage line sends only in direct Spaces, only to a peer with an active Assignment who has messaged it since that Assignment. SMS and MMS require current Platforms authorization for the sender and every recipient; campaign eligibility is required unless every recipient is in-network. API reference: https://photon.codes/docs/beta/api-reference/messages/send-a-message
Set iMessage line contact profile Changes the line's mode and custom names when expectedVersion matches. Custom mode needs a first or last name; an omitted name becomes null. Staying custom keeps the picture; entering custom starts without one. Project and none remove custom names and picture. None deletes the native profile. Returns 200 after confirmation and commit, 202 while pending, or a problem on failure. Repeat the same request with the same Idempotency-Key after Retry-After to await the result, including after a lost response. Results are retained for 24 hours; key replay precedes version validation. A different change while one is pending returns 409. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/imessage/set-imessage-line-contact-profile
Set iMessage profile sharing Turns automatic sharing of the iMessage contact profile on or off for the project's dedicated lines. Lines in none mode and shared lines never share. Writing the current value changes nothing, so a repeated request needs no Idempotency-Key. The setting does not change any line's resourceVersion. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/imessage/set-imessage-profile-sharing
Set typing in a Space Saves one transient typing update as an authorized Agent in this Space. Returns the dispatched Message with HTTP 202. Successful provider handoff ends in accepted; rejection or expiry ends in failed. Repeat true to refresh; false stops where supported. Callers control refreshes. Unsupported platforms return OPERATION_UNAVAILABLE. API reference: https://photon.codes/docs/beta/api-reference/spaces/set-typing-in-a-space
Share a profile in a Space Saves one share of the sender line's selected contact profile (name and photo) with everyone in this Space, as an authorized Agent. Returns the dispatched Message with HTTP 202. Successful handoff to the platform ends in accepted; recipients confirm nothing, so a share never becomes delivered. A share refused at execution, or not started within two minutes, ends in failed. A line whose profile mode is none shares nothing, and the Message is accepted. A shared line returns PROFILE_UNAVAILABLE; a profile change still in progress returns PROFILE_NOT_READY. Unsupported platforms return OPERATION_UNAVAILABLE. API reference: https://photon.codes/docs/beta/api-reference/spaces/share-a-profile-in-a-space
Trigger sole-proprietor OTP Requests delivery of a verification code for an organization-owned sole-proprietor brand. A 202 response acknowledges the delivery request and does not mean the brand has been verified. Inspect the OTP status and submit the received code through verifyTenDlcBrandOtp. Requests may be rate limited. Supply the required Idempotency-Key header. Supply organization_id for the organization that owns the registration. API reference: https://photon.codes/docs/beta/api-reference/10dlc-brand-otp/trigger-sole-proprietor-otp
Unassign SMS line campaign Any project writer, including a scoped API key, may detach the campaign. The number and campaign remain owned. Requires a permanent Idempotency-Key and expectedVersion. Local eligibility is blocked immediately; provider detachment runs asynchronously. If the operation fails, its `error` is the problem of one of these codes: `SMS_CAMPAIGN_PROVIDER_REJECTED`, `SMS_CAMPAIGN_RECONCILIATION_REQUIRED`, `SMS_CAMPAIGN_REVOKED`. API reference: https://photon.codes/docs/beta/api-reference/sms-campaigns/unassign-sms-line-campaign
Unassign Voice line profile Removes a line's explicit override when the resource version matches so the line follows the project default. Profiles and the pstn_voice ability are unchanged. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/unassign-voice-line-profile
Update account Updates the supplied firstName and lastName fields on the authenticated account and returns the updated profile. Only the documented profile fields can be changed through this endpoint; profile-picture uploads and phone-number verification use their dedicated operations. Supply the required Idempotency-Key header. API reference: https://photon.codes/docs/beta/api-reference/account/update-account
Update agent profile Updates the supplied firstName and lastName fields in the project's agent profile and returns the updated profile. Avatar upload, commit and reset are separate operations. The caller must be authorized to change configuration for the selected project. Supply the required Idempotency-Key header. API reference: https://photon.codes/docs/beta/api-reference/agent-profile/update-agent-profile
Update default Voice profile Patches the default profile's protocol or mediaEncryption when expectedVersion matches. Omitted fields are preserved. Its server-assigned name is immutable, and directional configuration uses the profileId returned by this resource. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/update-default-voice-profile
Update project Updates the identified project's name and returns the updated project. The project slug is not a mutable field in this request. Use an authorized account or organization service-identity credential; a project API key is not accepted. Supply the required Idempotency-Key header. API reference: https://photon.codes/docs/beta/api-reference/projects/update-project
Correct a brand Updates a brand. A PATCH containing only supportEmail commits synchronously. Registry-facing and mixed changes use a durable correction: the complete revised profile becomes active atomically once the registry applies it, and if registration then fails the brand reports action_required with that profile and its failureReasons. On a brand whose registration was not accepted, the same PATCH fixes and resubmits it; resubmitting unchanged details returns REGISTRATION_DETAILS_UNCHANGED. A brand's profile type is immutable. API reference: https://photon.codes/docs/beta/api-reference/10dlc-brands/correct-a-brand
Update a campaign Updates campaign fields selected by updateMask, guarded by etag. Name changes are local and allowed in every state. Eligible rejected campaigns save content locally until resubmit. Ready campaigns allow asynchronous sample changes. Other states lock campaign content. API reference: https://photon.codes/docs/beta/api-reference/10dlc-campaigns/update-a-campaign
Update Voice profile Patches an additional profile's name, protocol, or mediaEncryption when expectedVersion matches. Omitted fields are preserved. The default profile's metadata changes only through PATCH /v1/projects/{id}/platforms/voice/profiles/default, so a name, protocol, or mediaEncryption patch addressed to its profileId is refused with 409. Directional configuration is managed through the profile's inbound and outbound endpoints. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/update-voice-profile
Update Voice outbound authentication Changes a SIP profile's outbound Digest algorithm when expectedVersion matches. The profileId may identify the default or an additional profile. This policy-only change preserves the password, username, and any previous-password grace deadline. SHA-256 is recommended; MD5 is a weaker legacy option. Returns non-secret outbound metadata and the profile version. Requires platforms:write bound to the path project. API reference: https://photon.codes/docs/beta/api-reference/voice/update-voice-outbound-authentication
Update webhook destination Updates the supplied URL, name, description, status or enabledEvents fields on a project's webhook destination and returns its updated configuration. The payload API version is not a mutable field in this request. Event selections are checked against the destination's versioned catalog; signing-secret rotation is a separate operation. Supply the required Idempotency-Key header. API reference: https://photon.codes/docs/beta/api-reference/webhook-destinations/update-webhook-destination