{"components":{"schemas":{"User":{"description":"A user of the app","example":{"first_name":"Brian","id":"usr_01j9dwavghe1ttppewekjjkfrx","last_name":"O'Conner","metadata":{"email":"boconner@toretti.family","user_id":"1234"},"photo_url":"https://toretti.family/people/brian.jpg"},"properties":{"first_name":{"description":"The user's first name.","type":"string"},"id":{"description":"Unique identifier for the object.","type":"string"},"last_name":{"description":"The user's last name.","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"photo_url":{"description":"URL of a photo to be used as the user's avatar.","format":"uri","type":"string"}},"required":["first_name"],"title":"User","type":"object"},"VoicemailReceivedEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"call":{"contact":{"email":"dom@toretto.family","first_name":"Dominic","id":"ctc_01ja88cboqffhswjx8zbak3ykk","last_name":"Toretto","metadata":{"car":"1970 Dodge Charger R/T"},"phone_number":"+18015551234"},"duration":184,"from":"+18015551234","id":"call_01jjnn7s0zfx5tdcsxjfy93et2","initiated_at":"2025-03-31T21:01:37Z","phone_number_id":"pn_01jsjwe4d9fx3tpymgtg958d9w","status":"completed","to":"+18015556789"},"duration":124,"id":"vml_01kfycac7rery81axwmpzcgpp8","recording_id":"rec_01kfyc9dgdec1avkgs7tng8htg"},"timestamp":"2024-10-21T23:29:41Z","type":"voicemail.received"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"call":{"description":"The call that resulted in this voicemail","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"duration":{"description":"The duration of the call in seconds","type":"integer"},"from":{"description":"The E.164 phone number of the caller","type":["string","null"]},"id":{"description":"The unique identifier for the call","type":"string"},"initiated_at":{"description":"When the call was initiated","format":"date-time","type":"string"},"phone_number_id":{"description":"The Surge phone number ID (e.g. pn_...)","type":["string","null"]},"status":{"description":"The status of the call","enum":["busy","canceled","completed","failed","in_progress","missed","no_answer","queued","ringing"],"type":"string"},"to":{"description":"The E.164 phone number of the callee","type":["string","null"]}},"required":["id","contact","duration","initiated_at","status"],"type":"object"},"duration":{"description":"The duration of the voicemail in seconds","type":"integer"},"id":{"description":"The unique identifier for the voicemail","type":"string"},"recording_id":{"description":"The unique identifier for the recording","type":"string"}},"required":["id","recording_id","duration","call"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"voicemail.received","description":"The type of the event. Always `voicemail.received` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"VoicemailReceivedEvent","type":"object"},"UserParams":{"description":"POST body for creating a user","example":{"first_name":"Brian","last_name":"O'Conner","metadata":{"email":"boconner@toretti.family","user_id":"1234"},"photo_url":"https://toretti.family/people/brian.jpg"},"properties":{"first_name":{"description":"The user's first name.","type":"string"},"last_name":{"description":"The user's last name.","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"photo_url":{"description":"URL of a photo to be used as the user's avatar.","format":"uri","type":"string"}},"required":["first_name"],"title":"UserParams","type":"object"},"TokenParams":{"description":"A request to create a token","example":{"duration_seconds":900},"properties":{"duration_seconds":{"description":"For how many seconds the token should be accepted. Defaults to 15 minutes.","example":900,"maximum":3600,"minimum":15,"type":"integer"}},"title":"TokenParams","type":"object"},"AccountList":{"description":"A paginated list of accounts","properties":{"data":{"description":"The list of accounts","items":{"$ref":"#/components/schemas/Account"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"title":"AccountList","type":"object"},"Blast":{"description":"A Blast is a message sent to multiple recipients at once.","example":{"attachments":[{"url":"https://example.com/image.jpg"}],"body":"Join us for our grand opening!","id":"bst_01j9dy8mdzfn3r0e8x1tbdrdrf","name":"Grand Opening Announcement","send_at":"2024-02-01T15:00:00Z"},"properties":{"attachments":{"items":{"properties":{"url":{"description":"The URL of the attachment.","type":"string"}},"type":"object"},"type":"array"},"body":{"description":"The message body.","type":["string","null"]},"id":{"description":"Unique identifier for the object.","type":"string"},"name":{"description":"Optional name for the blast.","type":"string"},"send_at":{"description":"When the blast will be or was sent.","format":"date-time","type":"string"}},"title":"Blast","type":"object"},"ConversationPhoneNumber":{"description":"This is the phone number tied to the Surge account.","example":{"id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"name":"(801) 555-1234","number":"+18015551234","type":"local"},"properties":{"id":{"description":"Unique identifier for the phone number","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"description":"A human-readable name for the phone number","type":["string","null"]},"number":{"description":"The canonical format of the phone number.","example":"+18015551234","format":"phone-number","pattern":"^\\+[1-9]\\d{6,14}$|^\\d{5,6}$","type":"string"},"type":{"description":"Whether the phone number is local, toll-free, or short code","enum":["local","toll_free","short_code","demo"],"type":"string"}},"required":["id","metadata","name","number","type"],"title":"ConversationPhoneNumber","type":"object"},"MessageFailedEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"attachments":[],"blast_id":null,"body":"Dude, I almost had you!","conversation":{"contact":{"first_name":"Dominic","id":"ctc_01ja88cboqffhswjx8zbak3ykk","last_name":"Toretto","phone_number":"+18015551234"},"id":"cnv_01jav8xy7fe4nsay3c9deqxge9","phone_number":{"campaign_id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2","id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"name":"(801) 555-6789","number":"+18015556789","type":"local"}},"failed_at":"2024-10-21T23:29:42Z","failure_reason":"carrier_error","id":"msg_01jjnn7s0zfx5tdcsxjfy93et2","metadata":{"order_id":"12345"},"status":"failed"},"timestamp":"2024-10-21T23:29:41Z","type":"message.failed"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"attachments":{"description":"Attachments included with the message","items":{"properties":{"id":{"description":"The unique identifier for the attachment","type":"string"},"type":{"description":"The type of attachment","enum":["file","image","link","contact","video"],"type":"string"},"url":{"description":"The URL to download the attachment","type":"string"}},"required":["id","type","url"],"type":"object"},"type":"array"},"blast_id":{"description":"The ID of the blast this message belongs to, if any. This can be used to attribute messages back to a specific blast.","type":"string"},"body":{"description":"The content of the message","type":["string","null"]},"conversation":{"description":"The conversation this message belongs to","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"id":{"description":"The unique identifier for the conversation","type":"string"},"phone_number":{"$ref":"#/components/schemas/PhoneNumber"}},"required":["id","phone_number","contact"],"type":"object"},"failed_at":{"description":"When the message failed","format":"date-time","type":"string"},"failure_reason":{"description":"The reason the message failed to be delivered","type":"string"},"id":{"description":"The unique identifier for the message","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"status":{"description":"The message status represented by this event","enum":["failed"],"type":"string"}},"required":["id","body","metadata","status","failed_at","failure_reason","conversation"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"message.failed","description":"The type of the event. Always `message.failed` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"MessageFailedEvent","type":"object"},"AccountUpdateParams":{"description":"Parameters for updating an existing account.","example":{"brand_name":"DT Precision Auto","name":"D·T Precision Auto Shop","organization":{"address":{"country":"US","line1":"2640 Huron St","line2":null,"locality":"Los Angeles","name":"DT Precision Auto","postal_code":"90065","region":"CA"},"contact":{"email":"dom@dtprecisionauto.com","first_name":"Dominic","last_name":"Toretto","phone_number":"+13235556439","title":"other","title_other":"Owner"},"country":"US","email":"dom@dtprecisionauto.com","identifier":"123456789","identifier_type":"ein","industry":"automotive","mobile_number":"+13235556439","regions_of_operation":["usa_and_canada"],"registered_name":"DT Precision Auto LLC","stock_exchange":null,"stock_symbol":null,"type":"llc","website":"https://dtprecisionauto.com"},"time_zone":"America/Los_Angeles"},"properties":{"brand_name":{"description":"The name by which the people this account communicates with know it. If not provided, this will match the name field.","type":"string"},"name":{"description":"The name of the account that will be visible for your internal organizational purposes. This will also be the default public-facing brand name unless you also set a `brand_name`, but otherwise the account name will never be displayed anywhere outside of Surge HQ, and may include your ID for the account or anything else that may help you.","type":"string"},"organization":{"$ref":"#/components/schemas/OrganizationParams"},"time_zone":{"description":"The time zone for the account","example":"America/Los_Angeles","nullable":true,"type":"string"}},"required":[],"title":"AccountUpdateParams","type":"object"},"CampaignList":{"description":"A paginated list of campaigns","properties":{"data":{"description":"The list of campaigns","items":{"$ref":"#/components/schemas/Campaign"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"title":"CampaignList","type":"object"},"Verification":{"description":"A phone number verification","example":{"attempt_count":0,"id":"vfn_01jayh15c2f2xamftg0xpyq1nj","phone_number":"+18015551234","status":"pending"},"properties":{"attempt_count":{"description":"The number of times the code has been attempted.","type":"integer"},"id":{"description":"Unique identifier for the object.","type":"string"},"phone_number":{"description":"The phone number being verified. In E.164 format.","example":"+18015551234","format":"phone-number","pattern":"^\\+[1-9]\\d{6,14}$","type":"string"},"status":{"description":"The current status of the verification.","enum":["pending","verified","exhausted","expired"],"type":"string"}},"required":["id","attempt_count","phone_number","status"],"title":"Verification","type":"object"},"TollFreeCampaign":{"description":"A toll-free campaign registration for a phone number.","properties":{"description":{"type":"string"},"id":{"description":"The toll-free campaign ID","type":"string"},"includes":{"items":{"enum":["age_gated"],"type":"string"},"type":"array"},"message_samples":{"items":{"type":"string"},"type":"array"},"phone_number_id":{"description":"The toll-free phone number ID","type":"string"},"privacy_policy_url":{"format":"uri","type":"string"},"status":{"description":"The current status of the toll-free campaign.","enum":["active","canceled","created","in_review","rejected"],"type":"string"},"terms_and_conditions_url":{"format":"uri","type":"string"},"use_cases":{"items":{"enum":["two_factor_authentication","account_notification","customer_care","charity","delivery_notification","fraud_alert","event","higher_education","k12_education","marketing","polling_voting","political","public_service_announcement","security_alert"],"type":"string"},"type":"array"}},"required":["id","phone_number_id","status","use_cases","description","message_samples","includes","privacy_policy_url","terms_and_conditions_url"],"title":"TollFreeCampaign","type":"object"},"ConversationParams":{"description":"Params for selecting or creating a new conversation. Either the id or the Contact must be given.","example":{"contact":{"first_name":"Dominic","last_name":"Toretto","phone_number":"+18015551234"},"phone_number":"+18015556789"},"properties":{"contact":{"$ref":"#/components/schemas/ContactParams"},"phone_number":{"description":"The phone number from which to send the message. This can be either the phone number in E.164 format or a Surge phone number id.","example":"+18015552345","pattern":"^\\+[1-9]\\d{6,14}$|^\\d{5,6}$|^pn_[[:alnum:]]{26}$","type":"string"}},"required":["contact"],"title":"ConversationParams","type":"object"},"PhoneNumberList":{"description":"A paginated list of phone numbers","example":{"data":[{"campaign":null,"campaign_id":null,"id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"name":"(801) 555-1234","number":"+18015551234","type":"local"}],"pagination":{"next_cursor":null,"previous_cursor":null}},"properties":{"data":{"description":"The list of phone numbers","items":{"$ref":"#/components/schemas/PhoneNumber"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"title":"PhoneNumberList","type":"object"},"TokenResponse":{"description":"Response when token has been created successfully","example":{"token":"eyJhbGciOiJFZERTQSIsImtpZCI6InNnbl8wMWp5bWowZ3AwZjNidmJmMmpyazRoYnd0ayIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3NTA4ODkyMDgsInN1YiI6InVzcl8wMWp5bWdkZnJwZWMyYXNjNW0wejNhNmZyOSJ9.zKayo3EDrUm1Hw8URrofuYwajgyTu6dH2H0FEuRExprP1IV66FHa8wC3SfdzV7sR3AjDGAwkuAXztScq6rBnBw"},"properties":{"token":{"description":"The created token.","type":"string"}},"title":"TokenResponse","type":"object"},"Error":{"description":"An error response","example":{"message":"The requested resource was not found.","type":"not_found"},"properties":{"detail":{"additionalProperties":true,"description":"Additional details about the error.","type":"object"},"message":{"description":"A human-readable error message.","example":"The requested resource was not found.","type":"string"},"type":{"description":"A unique error code.","example":"not_found","type":"string"}},"required":["type","message"],"title":"Error","type":"object"},"ContactList":{"description":"A paginated list of contacts","example":{"data":[{"email":"dom@toretto.family","first_name":"Dominic","id":"ctc_01j9dy8mdzfn3r0e8x1tbdrdrf","last_name":"Toretto","metadata":{"car":"1970 Dodge Charger R/T"},"phone_number":"+18015551234"}],"pagination":{"next_cursor":null,"previous_cursor":null}},"properties":{"data":{"description":"The list of contacts","items":{"$ref":"#/components/schemas/Contact"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"title":"ContactList","type":"object"},"Attachment":{"description":"An Attachment is a file that can be sent with a message.","example":{"id":"att_01j9e0m1m6fc38gsv2vkfqgzz2","type":"image","url":"https://api.surge.app/attachments/att_01jbwyqj7rejzat7pq03r7fgmf"},"properties":{"id":{"description":"Unique identifier for the object.","type":"string"},"type":{"description":"The type of attachment.","enum":["file","image","link","contact","video"],"type":"string"},"url":{"description":"The URL of the attachment.","type":"string"}},"title":"Attachment","type":"object"},"CampaignApprovedEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2","status":"active"},"timestamp":"2024-10-21T23:29:41Z","type":"campaign.approved"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"id":{"description":"The unique identifier for the campaign","type":"string"},"status":{"description":"The status of the campaign. Will always be `active` for this event.","enum":["active"],"type":"string"}},"required":["id","status"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"campaign.approved","description":"The type of the event. Always `campaign.approved` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"CampaignApprovedEvent","type":"object"},"AvailablePhoneNumber":{"description":"A phone number available for purchase from Surge inventory","example":{"country":"US","number":"+18015551234","type":"local"},"properties":{"country":{"description":"ISO country code for the phone number","enum":["US","CA"],"example":"US","type":"string"},"number":{"description":"The phone number in E.164 format","example":"+18015551234","format":"phone-number","pattern":"^\\+[1-9]\\d{6,14}$","type":"string"},"type":{"description":"Whether the phone number is local or toll-free","enum":["local","toll_free"],"example":"local","type":"string"}},"required":["country","number","type"],"title":"AvailablePhoneNumber","type":"object"},"ContactOptedInEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"id":"ctc_01ja88cboqffhswjx8zbak3ykk"},"timestamp":"2024-10-21T23:29:41Z","type":"contact.opted_in"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"id":{"description":"The unique identifier for the contact","type":"string"}},"required":["id"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"contact.opted_in","description":"The type of the event. Always `contact.opted_in` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"ContactOptedInEvent","type":"object"},"PhoneNumberAttachedToCampaignEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"campaign":{"attachment_status":"attached","id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2"},"campaign_id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2","id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"name":"(801) 555-1234","number":"+18015551234","type":"local"},"timestamp":"2024-10-21T23:29:41Z","type":"phone_number.attached_to_campaign"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"campaign":{"description":"Campaign attachment details for this phone number","oneOf":[{"$ref":"#/components/schemas/PhoneNumberCampaign"},{"type":"null"}]},"campaign_id":{"deprecated":true,"description":"Deprecated. The unique identifier of the campaign this phone number is attached to","type":"string","x-stainless-deprecation-message":"Use `campaign.id` instead."},"id":{"description":"The unique identifier for the phone number","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"description":"A human-readable name for the phone number","type":["string","null"]},"number":{"description":"The phone number in E.164 format","type":"string"},"type":{"description":"Whether the phone number is local, toll-free, or short code","enum":["local","short_code","toll_free"],"type":"string"}},"required":["id","metadata","name","number","type","campaign","campaign_id"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"phone_number.attached_to_campaign","description":"The type of the event. Always `phone_number.attached_to_campaign` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"PhoneNumberAttachedToCampaignEvent","type":"object"},"ConversationCreatedEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"contact":{"first_name":"Dominic","id":"ctc_01ja88cboqffhswjx8zbak3ykk","last_name":"Toretto","phone_number":"+18015551234"},"id":"cnv_01jav8xy7fe4nsay3c9deqxge9","phone_number":{"campaign_id":null,"id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"name":"(801) 555-6789","number":"+18015556789","type":"local"}},"timestamp":"2024-10-21T23:29:41Z","type":"conversation.created"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"id":{"description":"The unique identifier for the conversation","type":"string"},"phone_number":{"$ref":"#/components/schemas/PhoneNumber"}},"required":["id","phone_number","contact"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"conversation.created","description":"The type of the event. Always `conversation.created` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"ConversationCreatedEvent","type":"object"},"MessageDeliveredEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"attachments":[{"id":"att_01jjnn75vgepj8bnnttfw1st5s","type":"image","url":"https://toretto.family/skyline.jpg"}],"blast_id":null,"body":"Dude, I almost had you!","conversation":{"contact":{"email":"dom@toretto.family","first_name":"Dominic","id":"ctc_01ja88cboqffhswjx8zbak3ykk","last_name":"Toretto","metadata":{"car":"1970 Dodge Charger R/T"},"phone_number":"+18015551234"},"id":"cnv_01jav8xy7fe4nsay3c9deqxge9","phone_number":{"campaign_id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2","id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"name":"(801) 555-6789","number":"+18015556789","type":"local"}},"delivered_at":"2024-10-21T23:29:42Z","id":"msg_01jjnn7s0zfx5tdcsxjfy93et2","metadata":{"order_id":"12345"},"status":"delivered"},"timestamp":"2024-10-21T23:29:41Z","type":"message.delivered"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"attachments":{"description":"Attachments included with the message","items":{"properties":{"id":{"description":"The unique identifier for the attachment","type":"string"},"type":{"description":"The type of attachment","enum":["file","image","link","contact","video"],"type":"string"},"url":{"description":"The URL where the attachment can be downloaded","type":"string"}},"required":["id","type","url"],"type":"object"},"type":"array"},"blast_id":{"description":"The ID of the blast this message belongs to, if any. This can be used to attribute messages back to a specific blast.","type":"string"},"body":{"description":"The content of the message","type":["string","null"]},"conversation":{"description":"The conversation this message belongs to","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"id":{"description":"The unique identifier for the conversation","type":"string"},"phone_number":{"$ref":"#/components/schemas/PhoneNumber"}},"required":["id","phone_number","contact"],"type":"object"},"delivered_at":{"description":"When the message was delivered","format":"date-time","type":"string"},"id":{"description":"The unique identifier for the message","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"status":{"description":"The message status represented by this event","enum":["delivered"],"type":"string"}},"required":["id","body","metadata","status","delivered_at","conversation"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"message.delivered","description":"The type of the event. Always `message.delivered` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"MessageDeliveredEvent","type":"object"},"Conversation":{"description":"A conversation with a Contact","example":{"contact":{"first_name":"Dominic","id":"ctc_01j9dy8mdzfn3r0e8x1tbdrdrf","last_name":"Toretto","phone_number":"+18015551234"},"id":"cnv_01j9e0dgmdfkj86c877ws0znae","phone_number":{"id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"name":"(801) 555-2345","number":"+18015552345","type":"local"}},"properties":{"contact":{"$ref":"#/components/schemas/Contact"},"id":{"description":"Unique identifier for the object.","type":"string"},"phone_number":{"$ref":"#/components/schemas/ConversationPhoneNumber"}},"required":["id","contact"],"title":"Conversation","type":"object"},"AudienceCreateParams":{"description":"Params for creating an audience","example":{"name":"The Family"},"properties":{"name":{"description":"The audience name.","maxLength":255,"type":"string"}},"required":["name"],"title":"AudienceCreateParams","type":"object"},"VerificationCheckParams":{"description":"Parameters for checking a Verification code","example":{"code":"123456"},"properties":{"code":{"description":"The Verification code that was received.","example":"123456","pattern":"^[0-9]{6}$","type":"string"}},"required":["code"],"title":"VerificationCheckParams","type":"object"},"BrandVerificationMessageResponse":{"description":"Response when a brand verification OTP send has been enqueued","example":{"status":"enqueued"},"properties":{"status":{"description":"Indicates the OTP send job was enqueued successfully.","enum":["enqueued"],"type":"string"}},"required":["status"],"title":"BrandVerificationMessageResponse","type":"object"},"AvailablePhoneNumberList":{"description":"A list of phone numbers available for purchase","example":{"data":[{"country":"US","number":"+18015551234","type":"local"}],"pagination":{"next_cursor":null,"previous_cursor":null}},"properties":{"data":{"description":"The list of available phone numbers","items":{"$ref":"#/components/schemas/AvailablePhoneNumber"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"title":"AvailablePhoneNumberList","type":"object"},"MessageSentEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"attachments":[{"id":"att_01jjnn75vgepj8bnnttfw1st5s","type":"image","url":"https://toretto.family/skyline.jpg"}],"blast_id":null,"body":"Dude, I almost had you!","conversation":{"contact":{"first_name":"Dominic","id":"ctc_01ja88cboqffhswjx8zbak3ykk","last_name":"Toretto","phone_number":"+18015551234"},"id":"cnv_01jav8xy7fe4nsay3c9deqxge9","phone_number":{"campaign_id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2","id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"name":"(801) 555-6789","number":"+18015556789","type":"local"}},"id":"msg_01jjnn7s0zfx5tdcsxjfy93et2","metadata":{"order_id":"12345"},"sent_at":"2024-10-21T23:29:41Z","status":"sent"},"timestamp":"2024-10-21T23:29:41Z","type":"message.sent"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"attachments":{"description":"Attachments included with the message","items":{"properties":{"id":{"description":"The unique identifier for the attachment","type":"string"},"type":{"description":"The type of attachment","enum":["file","image","link","contact","video"],"type":"string"},"url":{"description":"The URL to download the attachment","type":"string"}},"required":["id","type","url"],"type":"object"},"type":"array"},"blast_id":{"description":"The ID of the blast this message belongs to, if any. This can be used to attribute messages back to a specific blast.","type":"string"},"body":{"description":"The content of the message","type":["string","null"]},"conversation":{"description":"The conversation this message belongs to","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"id":{"description":"The unique identifier for the conversation","type":"string"},"phone_number":{"$ref":"#/components/schemas/PhoneNumber"}},"required":["id","phone_number","contact"],"type":"object"},"id":{"description":"The unique identifier for the message","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"sent_at":{"description":"When the message was sent","format":"date-time","type":"string"},"status":{"description":"The message status represented by this event","enum":["sent"],"type":"string"}},"required":["id","body","metadata","status","sent_at","conversation"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"message.sent","description":"The type of the event. Always `message.sent` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"MessageSentEvent","type":"object"},"RecordingList":{"description":"A paginated list of recordings","properties":{"data":{"description":"The list of recordings","items":{"$ref":"#/components/schemas/Recording"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"title":"RecordingList","type":"object"},"AccountStatus":{"description":"Response containing account status information","example":{"capabilities":{"local_messaging":{"errors":[{"field":"organization.registered_name","message":"The provided EIN doesn't match the organization's registered name.","type":"ein_mismatch"}],"fields_needed":[],"status":"error"},"phone_calls":{"errors":[],"fields_needed":[],"status":"ready"},"toll_free_messaging":{"errors":[],"fields_needed":["organization.contact.title_other","organization.mobile_number"],"status":"incomplete"}}},"properties":{"capabilities":{"additionalProperties":{"properties":{"errors":{"description":"A list of errors that will need corrected before capability is available to account.","items":{"properties":{"field":{"description":"A dot-delimited string representing the field that has an error, as in `organization.contact.phone_number`.","type":"string"},"message":{"description":"A human-readable string explaining the error.","type":"string"},"type":{"description":"A slug for the error type","type":"string"}},"required":["type","field","message"],"type":"object"},"type":"array"},"fields_needed":{"description":"A list of missing fields that are required for the capability. Nested field names are dot-delimited, as in `organization.address.region`.","items":{"type":"string"},"type":"array"},"status":{"description":"Whether the account is ready for the capability, has errors that need corrected, or is incomplete and requires missing data. If account has both missing and invalid fields, `error` will be preferred over `incomplete`.","enum":["error","incomplete","ready"],"type":"string"}},"required":["status","errors","fields_needed"],"type":"object"},"description":"An object where the fields are the capabilities passed in the `capabilities` query param, as in `local_messaging`.","type":"object"}},"required":["capabilities"],"title":"AccountStatus","type":"object"},"AudienceContactParams":{"description":"Params for adding an existing contact to a manual audience","example":{"id":"ctc_01j9dy8mdzfn3r0e8x1tbdrdrf"},"properties":{"id":{"description":"The ID of the contact to add. The contact must belong to the same account as the audience.","type":"string"}},"required":["id"],"title":"AudienceContactParams","type":"object"},"LinkFollowedEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"id":"lnk_01kedctzhxexdbr5xf2bht5q84","message":{"attachments":[],"blast_id":null,"body":"You have a new receipt from DT Precision Auto: https://yoursite.com/something?param=true","conversation":{"contact":{"email":null,"first_name":"Dominic","id":"ctc_01ja88cboqffhswjx8zbak3ykk","last_name":"Toretto","metadata":{},"phone_number":"+18015551234"},"id":"cnv_01jav8xy7fe4nsay3c9deqxge9","phone_number":{"campaign_id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2","id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"name":"(801) 555-6789","number":"+18015556789","type":"local"}},"id":"msg_01jjnn7s0zfx5tdcsxjfy93et2","metadata":{},"status":"delivered"},"message_id":"msg_01jjnn7s0zfx5tdcsxjfy93et2","url":"https://yoursite.com/something?param=true"},"timestamp":"2024-10-21T23:29:41Z","type":"link.followed"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"id":{"description":"The unique identifier for the link","type":"string"},"message":{"description":"The message that contained the shortened link, including its conversation, phone number, and contact. ","oneOf":[{"$ref":"#/components/schemas/Message"},{"type":"null"}],"type":["object","null"]},"message_id":{"deprecated":true,"description":"Deprecated. The unique identifier for the message that contained the link.","type":["string","null"],"x-stainless-deprecation-message":"Use `message.id` instead."},"url":{"description":"The original URL that was shortened","type":"string"}},"required":["id","message_id","message","url"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"link.followed","description":"The type of the event. Always `link.followed` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"LinkFollowedEvent","type":"object"},"CampaignParams":{"description":"Parameters for creating a new campaign. Either provide full campaign details or import using a TCR ID.","oneOf":[{"$ref":"#/components/schemas/StandardCampaignParams"},{"$ref":"#/components/schemas/ExternalCampaignParams"}],"title":"CampaignParams","type":"object"},"Organization":{"description":"The legal entity on whose behalf the account will be operated.","properties":{"address":{"description":"The address of the organization's headquarters.","properties":{"country":{"description":"The two character ISO 3166 country code. If none is provided, the organization's country code will be used.","nullable":true,"type":"string"},"line1":{"description":"The first line of the address, typically the number and street name","nullable":true,"type":"string"},"line2":{"description":"The second line of the address if needed, typically an apartment or suite number","nullable":true,"type":"string"},"locality":{"description":"The city or locality","nullable":true,"type":"string"},"name":{"description":"The name to which any mail should be addressed. If none is provided, this will default to the organization's registered_name","nullable":true,"type":"string"},"postal_code":{"description":"The postal code","nullable":true,"type":"string"},"region":{"description":"The state or region","maxLength":20,"nullable":true,"type":"string"}},"required":["name","line1","line2","locality","region","postal_code","country"],"type":"object"},"contact":{"description":"An object representing an individual who can be contacted if the carriers have any questions about the business.","properties":{"email":{"description":"An email address at which the individual can be reached. Typically an email using the same domain name as the website URL will be preferred (e.g. with a website domain of `https://dtprecisionauto.com`, an email like `dom@dtprecisionauto.com` will be preferred over one like `dom@anothergarage.com` or `dom.toretto@gmail.com`)","format":"email","nullable":true,"type":"string"},"first_name":{"description":"The first name (or given name) of the individual","nullable":true,"type":"string"},"last_name":{"description":"The last name (or family name) of the individual","nullable":true,"type":"string"},"phone_number":{"description":"A phone number at which the individual can be reached (E.164 format)","nullable":true,"type":"string"},"title":{"description":"The job title of the individual.","enum":["ceo","cfo","director","gm","vp","general_counsel","other"],"nullable":true,"type":"string"},"title_other":{"description":"If `other` is provided for the `title` field, this field should be used to provide the title of the individual","nullable":true,"type":"string"}},"required":["email","first_name","last_name","phone_number","title","title_other"],"type":"object"},"country":{"description":"The two character ISO 3166 country code for the country in which the organization is headquartered.","nullable":true,"type":"string"},"email":{"description":"For publicly traded companies, an email for a representative of the company to whom a verification email will be sent. This must be an email on the same domain as the company's website (e.g. with a website domain of `https://dtprecisionauto.com`, the email must use the same `@dtprecisionauto.com`)","format":"email","nullable":true,"type":"string"},"identifier":{"description":"The value of the identifier whose type is specified in the identifier_type field. For EIN, can be formatted with or without the hyphen. For CBN, must be exactly 9 digits. For VAT, provide only the numeric portion, between 2 and 20 digits.","maxLength":20,"minLength":2,"nullable":true,"type":"string"},"identifier_type":{"description":"The type of identifier being provided for the organization. Use \"ein\" for US organizations, \"cbn\" for Canadian organizations, or \"vat\" for supported international organizations.","enum":["ein","cbn","vat"],"nullable":true,"type":"string"},"industry":{"description":"The industry in which the organization operates.","enum":["agriculture","automotive","banking","construction","consumer","education","electronics","energy","engineering","fast_moving_consumer_goods","financial","fintech","food_and_beverage","government","healthcare","hospitality","insurance","jewelry","legal","manufacturing","media","not_for_profit","oil_and_gas","online","professional_services","raw_materials","real_estate","religion","retail","technology","telecommunications","transportation","travel"],"nullable":true,"type":"string"},"mobile_number":{"description":"For sole proprietors, this must be a valid US or Canadian mobile phone number to which a verification text message will be sent. (E.164 format)","nullable":true,"type":"string"},"regions_of_operation":{"description":"An array of regions in which the organization operates.","items":{"enum":["africa","asia","australia","europe","latin_america","usa_and_canada"],"type":"string"},"nullable":true,"type":"array"},"registered_name":{"description":"The legal name of the organization as registered with the IRS or other relevant authorities. For some applications, this will be matched against government records and should include all punctuation and everything else as well.","nullable":true,"type":"string"},"stock_exchange":{"description":"For publicly traded companies, this is the exchange on which the company's stock is traded.","enum":["amex","amx","asx","b3","bme","bse","fra","icex","jpx","jse","krx","lon","nasdaq","none","nyse","nse","omx","other","sehk","sgx","sse","sto","swx","szse","tsx","twse","vse"],"nullable":true,"type":"string"},"stock_symbol":{"description":"For publicly traded companies, the ticker symbol for the company's stock","nullable":true,"type":"string"},"type":{"description":"The type of organization","enum":["co_op","government","llc","non_profit","partnership","private_corporation","public_corporation","sole_proprietor"],"nullable":true,"type":"string"},"website":{"description":"The URL of the website for this organization. The website should be publicly available, clearly reflect the organization's purpose, and the URL should start with `https://`","nullable":true,"type":"string"}},"required":["address","contact","country","email","identifier","identifier_type","industry","mobile_number","regions_of_operation","registered_name","stock_exchange","stock_symbol","type","website"],"title":"Organization","type":"object"},"Account":{"description":"Response containing account information.","example":{"brand_name":"DT Precision Auto","id":"acct_01jpqjvfg9enpt7pyxd60pcmxj","name":"Account #2840 - DT Precision Auto","organization":{"address":{"country":"US","line1":"2640 Huron St","line2":null,"locality":"Los Angeles","name":"DT Precision Auto","postal_code":"90065","region":"CA"},"contact":{"email":"dom@dtprecisionauto.com","first_name":"Dominic","last_name":"Toretto","phone_number":"+13235556439","title":"other","title_other":"Owner"},"country":"US","email":"dom@dtprecisionauto.com","identifier":"123456789","identifier_type":"ein","industry":"automotive","mobile_number":"+13235556439","regions_of_operation":["usa_and_canada"],"registered_name":"DT Precision Auto LLC","stock_exchange":null,"stock_symbol":null,"type":"llc","website":"https://dtprecisionauto.com"},"time_zone":"America/Los_Angeles"},"properties":{"brand_name":{"description":"The name by which the people this account communicates with know it. If not provided, this will match the name field.","nullable":true,"type":"string"},"id":{"description":"The account ID","type":"string"},"name":{"description":"The name of the account that will be visible for your internal organizational purposes. This will also be the default public-facing brand name unless you also set a `brand_name`, but otherwise the account name will never be displayed anywhere outside of Surge HQ, and may include your ID for the account or anything else that may help you.","type":"string"},"organization":{"$ref":"#/components/schemas/Organization"},"time_zone":{"description":"This is the time zone in which the account is headquartered. This time zone may be used for compliance with TCPA restrictions on when messages may be sent.","example":"America/Los_Angeles","nullable":true,"type":"string"}},"required":["brand_name","id","name","organization","time_zone"],"title":"Account","type":"object"},"PhoneNumberCampaign":{"description":"Campaign attachment details for a domestic local phone number","example":{"attachment_status":"attached","id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2"},"properties":{"attachment_status":{"description":"The current campaign attachment status for this phone number.","enum":["attached","attachment_pending","detached","detachment_pending"],"type":"string"},"id":{"description":"The unique identifier of the campaign this phone number is attached to","type":"string"}},"required":["id","attachment_status"],"title":"PhoneNumberCampaign","type":"object"},"MessageReceivedEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"attachments":[{"id":"att_01jav8z6x1j4m1b3w8v2jz7j3r","type":"image","url":"https://toretto.family/image.jpg"}],"blast_id":null,"body":"I don't have friends, I got family.","conversation":{"contact":{"first_name":"Dominic","id":"ctc_01ja88cboqffhswjx8zbak3ykk","last_name":"Toretto","phone_number":"+18015551234"},"id":"cnv_01jav8xy7fe4nsay3c9deqxge9","phone_number":{"campaign_id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2","id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"name":"(801) 555-6789","number":"+18015556789","type":"local"}},"id":"msg_01jav96823f9x9054d6gyzpp16","metadata":{"order_id":"12345"},"received_at":"2024-10-22T23:32:49Z","status":"received"},"timestamp":"2024-10-21T23:29:41Z","type":"message.received"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"attachments":{"description":"Attachments included with the message","items":{"properties":{"id":{"description":"The unique identifier for the attachment","type":"string"},"type":{"description":"The type of attachment","enum":["file","image","link","contact","video"],"type":"string"},"url":{"description":"The URL to download the attachment","type":"string"}},"required":["id","type","url"],"type":"object"},"type":"array"},"blast_id":{"description":"The ID of the blast this message belongs to, if any. This can be used to attribute messages back to a specific blast.","type":"string"},"body":{"description":"The content of the message","type":["string","null"]},"conversation":{"description":"The conversation this message belongs to","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"id":{"description":"The unique identifier for the conversation","type":"string"},"phone_number":{"$ref":"#/components/schemas/PhoneNumber"}},"required":["id","phone_number","contact"],"type":"object"},"id":{"description":"The unique identifier for the message","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"received_at":{"description":"When the message was received","format":"date-time","type":"string"},"status":{"description":"The message status represented by this event","enum":["received"],"type":"string"}},"required":["id","body","metadata","status","received_at","conversation"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"message.received","description":"The type of the event. Always `message.received` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"MessageReceivedEvent","type":"object"},"RecordingCompletedEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"call":{"contact":{"email":"dom@toretto.family","first_name":"Dominic","id":"ctc_01ja88cboqffhswjx8zbak3ykk","last_name":"Toretto","metadata":{"car":"1970 Dodge Charger R/T"},"phone_number":"+18015551234"},"duration":184,"from":"+18015551234","id":"call_01jjnn7s0zfx5tdcsxjfy93et2","initiated_at":"2025-03-31T21:01:37Z","phone_number_id":"pn_01jsjwe4d9fx3tpymgtg958d9w","status":"completed","to":"+18015556789"},"duration":124,"id":"rec_01kfyc9dgdec1avkgs7tng8htg"},"timestamp":"2024-10-21T23:29:41Z","type":"recording.completed"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"call":{"description":"The call that produced this recording","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"duration":{"description":"The duration of the call in seconds","type":"integer"},"from":{"description":"The E.164 phone number of the caller","type":["string","null"]},"id":{"description":"The unique identifier for the call","type":"string"},"initiated_at":{"description":"When the call was initiated","format":"date-time","type":"string"},"phone_number_id":{"description":"The Surge phone number ID (e.g. pn_...)","type":["string","null"]},"status":{"description":"The status of the call","enum":["busy","canceled","completed","failed","in_progress","missed","no_answer","queued","ringing"],"type":"string"},"to":{"description":"The E.164 phone number of the callee","type":["string","null"]}},"required":["id","contact","duration","initiated_at","status"],"type":"object"},"duration":{"description":"The duration of the recording in seconds","type":"integer"},"id":{"description":"The unique identifier for the recording","type":"string"}},"required":["id","duration","call"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"recording.completed","description":"The type of the event. Always `recording.completed` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"RecordingCompletedEvent","type":"object"},"BlastParams":{"description":"Parameters for creating a Blast","example":{"attachments":[{"url":"https://example.com/image.jpg"}],"body":"Join us for our grand opening!","from":"+18015552345","name":"Grand Opening Announcement","send_at":"2024-02-01T15:00:00Z","to":["aud_01j9dy8mdzfn3r0e8x1tbdrdrf","ctc_01j9dy8mdzfn3r0e8x1tbdrdrf","+18015551234","+18015555678"]},"properties":{"attachments":{"items":{"$ref":"#/components/schemas/AttachmentParams"},"type":"array"},"body":{"description":"The message body.","type":["string","null"]},"contacts":{"deprecated":true,"description":"Deprecated. Use `to` instead.","items":{"example":"ctc_01jxwtp1vse91twb5bj977gav9","format":"id","type":"string"},"type":"array","x-stainless-deprecation-message":"Use `to` to specify recipients instead."},"from":{"description":"The phone number from which to send the blast. This can be either the phone number in E.164 format or a Surge phone number id. If not provided, the account's default phone number is used.","example":"+18015552345","pattern":"^\\+[1-9]\\d{6,14}$|^\\d{5,6}$|^pn_[[:alnum:]]{26}$","type":"string"},"name":{"description":"Optional name for the blast.","type":"string"},"segments":{"deprecated":true,"description":"Deprecated. Use `to` with audience IDs instead.","items":{"example":"aud_01jxwtwzqhfykb31dt6mvpsa9k","format":"id","type":"string"},"type":"array","x-stainless-deprecation-message":"Use `to` with audience IDs (`aud_...`) to specify audience recipients instead."},"send_at":{"description":"When to send the blast. If not provided, sends immediately.","format":"date-time","type":"string"},"to":{"description":"List of recipients to whom the blast should be sent. This can be a combination of contact IDs, audience IDs, and phone numbers.","items":{"oneOf":[{"example":"ctc_01jxwtp1vse91twb5bj977gav9","format":"id","type":"string"},{"example":"aud_01jxwtwzqhfykb31dt6mvpsa9k","format":"id","type":"string"},{"example":"+18015551234","format":"phone-number","pattern":"^\\+[1-9]\\d{6,14}$","type":"string"}]},"type":"array"}},"required":[],"title":"BlastParams","type":"object"},"Message":{"description":"A Message is a communication sent to a Contact.","example":{"attachments":[{"id":"att_01j9e0m1m6fc38gsv2vkfqgzz2","type":"image","url":"https://api.surge.app/attachments/att_01jbwyqj7rejzat7pq03r7fgmf"}],"blast_id":null,"body":"Thought you could leave without saying goodbye?","conversation":{"contact":{"first_name":"Dominic","id":"ctc_01j9dy8mdzfn3r0e8x1tbdrdrf","last_name":"Toretto","phone_number":"+18015551234"},"id":"cnv_01j9e0dgmdfkj86c877ws0znae","phone_number":{"id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"number":"+18015552345","type":"local"}},"id":"msg_01j9e0m1m6fc38gsv2vkfqgzz2","metadata":{"external_id":"12345"},"status":"delivered"},"properties":{"attachments":{"items":{"$ref":"#/components/schemas/Attachment"},"type":"array"},"blast_id":{"description":"The ID of the blast this message belongs to, if any. This can be used to attribute messages back to a specific blast.","type":["string","null"]},"body":{"description":"The message body.","type":["string","null"]},"conversation":{"$ref":"#/components/schemas/Conversation"},"id":{"description":"Unique identifier for the object.","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"status":{"description":"The current status of the message.","enum":["pending","received","sent","delivered","failed"],"type":"string"}},"title":"Message","type":"object"},"PhoneNumber":{"description":"A phone number that can be used to send and receive messages and calls","example":{"campaign":{"attachment_status":"attached","id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2"},"campaign_id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2","id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"name":"(801) 555-1234","number":"+18015551234","type":"local"},"properties":{"campaign":{"description":"Campaign attachment details for domestic local numbers, or null for other types of numbers and local numbers without a campaign","oneOf":[{"$ref":"#/components/schemas/PhoneNumberCampaign"},{"type":"null"}]},"campaign_id":{"deprecated":true,"description":"Deprecated. The unique identifier of the campaign this phone number is attached to, if any","type":["string","null"],"x-stainless-deprecation-message":"Use `campaign.id` instead."},"id":{"description":"Unique identifier for the phone number","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"description":"A human-readable name for the phone number","type":["string","null"]},"number":{"description":"The phone number in E.164 format","example":"+18015551234","format":"phone-number","pattern":"^\\+[1-9]\\d{6,14}$","type":"string"},"type":{"description":"Whether the phone number is local, toll-free, or short code","enum":["local","short_code","toll_free"],"type":"string"}},"required":["id","metadata","name","number","type","campaign","campaign_id"],"title":"PhoneNumber","type":"object"},"ContactOptedOutEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"id":"ctc_01ja88cboqffhswjx8zbak3ykk"},"timestamp":"2024-10-21T23:29:41Z","type":"contact.opted_out"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"id":{"description":"The unique identifier for the contact","type":"string"}},"required":["id"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"contact.opted_out","description":"The type of the event. Always `contact.opted_out` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"ContactOptedOutEvent","type":"object"},"AttachmentParams":{"description":"Params for creating an attachment","example":{"url":"https://toretto.family/coronas.gif"},"properties":{"url":{"description":"The URL of the attachment.","type":"string"}},"required":["url"],"title":"AttachmentParams","type":"object"},"VerificationCheck":{"description":"The result of checking a Verification code","example":{"result":"ok","verification":{"attempt_count":1,"id":"vfn_01jayh15c2f2xamftg0xpyq1nj","phone_number":"+18015551234","status":"verified"}},"properties":{"result":{"description":"The result of the code check.","enum":["ok","incorrect","exhausted","expired","already_verified"],"type":"string"},"verification":{"$ref":"#/components/schemas/Verification"}},"title":"VerificationCheck","type":"object"},"OrganizationParams":{"description":"Parameters describing the legal entity on whose behalf the account will be operated.","properties":{"address":{"description":"The address of the organization's headquarters.","properties":{"country":{"description":"The two character ISO 3166 country code. If none is provided, the organization's country code will be used.","nullable":true,"type":"string"},"line1":{"description":"The first line of the address, typically the number and street name","nullable":true,"type":"string"},"line2":{"description":"The second line of the address if needed, typically an apartment or suite number","nullable":true,"type":"string"},"locality":{"description":"The city or locality","nullable":true,"type":"string"},"name":{"description":"The name to which any mail should be addressed. If none is provided, this will default to the organization's registered_name","nullable":true,"type":"string"},"postal_code":{"description":"The postal code","nullable":true,"type":"string"},"region":{"description":"The state or region","maxLength":20,"nullable":true,"type":"string"}},"type":"object"},"contact":{"description":"An object representing an individual who can be contacted if Surge or our carrier partners have any questions about the business. If you are registering on behalf of your customer, this must be a contact from your customer's company rather than your own. The individual will likely never be contacted unless there are issues with spam.","nullable":true,"properties":{"email":{"description":"An email address at which the individual can be reached. Typically an email using the same domain name as the website URL will be preferred (e.g. with a website domain of `https://dtprecisionauto.com`, an email like `dom@dtprecisionauto.com` will be preferred over one like `dom@anothergarage.com` or `dom.toretto@gmail.com`. `dtprecisionauto@gmail.com` would also be acceptable, but not preferred)","format":"email","nullable":true,"type":"string"},"first_name":{"description":"The first name (or given name) of the individual","nullable":true,"type":"string"},"last_name":{"description":"The last name (or family name) of the individual","nullable":true,"type":"string"},"phone_number":{"description":"A phone number at which the individual can be reached (E.164 format)","nullable":true,"type":"string"},"title":{"description":"The job title of the individual.","enum":["ceo","cfo","director","gm","vp","general_counsel","other"],"nullable":true,"type":"string"},"title_other":{"description":"If `other` is provided for the `title` field, this field should be used to provide the title of the individual","nullable":true,"type":"string"}},"type":"object"},"country":{"description":"The two character ISO 3166 country code for the country in which the organization is headquartered.","nullable":true,"type":"string"},"email":{"description":"For publicly traded companies, an email for a representative of the company to whom a verification email will be sent. This must be an email on the same domain as the company's website (e.g. with a website domain of `https://dtprecisionauto.com`, the email must use the same `@dtprecisionauto.com`)","format":"email","nullable":true,"type":"string"},"identifier":{"description":"The value of the identifier whose type is specified in the identifier_type field. For EIN, can be formatted with or without the hyphen. For CBN, must be exactly 9 digits. For VAT, provide only the numeric portion, between 2 and 20 digits.","maxLength":20,"minLength":2,"nullable":true,"type":"string"},"identifier_type":{"description":"The type of identifier being provided for the organization. Use \"ein\" for US organizations, \"cbn\" for Canadian organizations, or \"vat\" for supported international organizations.","enum":["ein","cbn","vat"],"nullable":true,"type":"string"},"industry":{"description":"The industry in which the organization operates.","enum":["agriculture","automotive","banking","construction","consumer","education","electronics","energy","engineering","fast_moving_consumer_goods","financial","fintech","food_and_beverage","government","healthcare","hospitality","insurance","jewelry","legal","manufacturing","media","not_for_profit","oil_and_gas","online","professional_services","raw_materials","real_estate","religion","retail","technology","telecommunications","transportation","travel"],"nullable":true,"type":"string"},"mobile_number":{"description":"For sole proprietors, this must be a valid US or Canadian mobile phone number to which a verification text message will be sent. (E.164 format)","nullable":true,"type":"string"},"regions_of_operation":{"description":"An array of regions in which the organization operates.","items":{"enum":["africa","asia","australia","europe","latin_america","usa_and_canada"],"type":"string"},"nullable":true,"type":"array"},"registered_name":{"description":"The legal name of the organization as registered with the IRS or other relevant authorities. For some applications, this will be matched against government records and should include all punctuation and everything else as well.","nullable":true,"type":"string"},"stock_exchange":{"description":"For publicly traded companies, this is the exchange on which the company's stock is traded.","enum":["amex","amx","asx","b3","bme","bse","fra","icex","jpx","jse","krx","lon","nasdaq","none","nyse","nse","omx","other","sehk","sgx","sse","sto","swx","szse","tsx","twse","vse"],"nullable":true,"type":"string"},"stock_symbol":{"description":"For publicly traded companies, the ticker symbol for the company's stock","nullable":true,"type":"string"},"type":{"description":"The type of organization","enum":["co_op","government","llc","non_profit","partnership","private_corporation","public_corporation","sole_proprietor"],"nullable":true,"type":"string"},"website":{"description":"The URL of the website for this organization. The website should be publicly available, clearly reflect the organization's purpose, and the URL should start with `https://`","nullable":true,"type":"string"}},"title":"OrganizationParams","type":"object"},"AccountParams":{"description":"Parameters for creating a new account.","example":{"brand_name":"DT Precision Auto","name":"Account #2840 - DT Precision Auto","organization":{"address":{"country":"US","line1":"2640 Huron St","line2":null,"locality":"Los Angeles","name":"DT Precision Auto","postal_code":"90065","region":"CA"},"contact":{"email":"dom@dtprecisionauto.com","first_name":"Dominic","last_name":"Toretto","phone_number":"+13235556439","title":"other","title_other":"Owner"},"country":"US","email":"dom@dtprecisionauto.com","identifier":"123456789","identifier_type":"ein","industry":"automotive","mobile_number":"+13235556439","regions_of_operation":["usa_and_canada"],"registered_name":"DT Precision Auto LLC","stock_exchange":null,"stock_symbol":null,"type":"llc","website":"https://dtprecisionauto.com"},"time_zone":"America/Los_Angeles"},"properties":{"brand_name":{"description":"The name by which the people this account communicates with know it. If not provided, this will match the name field.","nullable":true,"type":"string"},"name":{"description":"The name of the account that will be visible for your internal organizational purposes. This will also be the default public-facing brand name unless you also set a `brand_name`, but otherwise the account name will never be displayed anywhere outside of Surge HQ, and may include your ID for the account or anything else that may help you.","type":"string"},"organization":{"$ref":"#/components/schemas/OrganizationParams"},"time_zone":{"description":"This is the time zone in which the account is headquartered. This time zone may be used for compliance with TCPA restrictions on when messages may be sent.","example":"America/Los_Angeles","type":"string"}},"required":["name"],"title":"AccountParams","type":"object"},"ContactParams":{"description":"Parameters for creating a contact","example":{"email":"dom@toretto.family","first_name":"Dominic","last_name":"Toretto","metadata":{"car":"1970 Dodge Charger R/T"},"outbound_disabled":false,"phone_number":"+18015551234"},"properties":{"email":{"description":"The contact's email address.","format":"email","type":"string"},"first_name":{"description":"The contact's first name.","type":"string"},"last_name":{"description":"The contact's last name.","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"outbound_disabled":{"description":"Whether outbound messaging should be manually disabled for the contact.","type":"boolean"},"phone_number":{"description":"The contact's phone number in E.164 format.","example":"+18015551234","format":"phone-number","pattern":"^\\+[1-9]\\d{6,14}$","type":"string"}},"required":["phone_number"],"title":"ContactParams","type":"object"},"TollFreeCampaignParams":{"description":"Parameters for creating a toll-free campaign through Surge","properties":{"consent_flows":{"items":{"oneOf":[{"properties":{"script":{"maxLength":2000,"minLength":20,"type":"string"},"type":{"enum":["verbal"],"type":"string"}},"required":["type","script"],"type":"object"},{"properties":{"form_url":{"format":"uri","type":"string"},"owner":{"enum":["brand","platform"],"type":"string"},"screenshot":{"properties":{"reason":{"enum":["behind_login","under_construction","other"],"type":"string"},"reason_other":{"maxLength":500,"minLength":1,"type":"string"},"urls":{"items":{"format":"uri","type":"string"},"maxItems":5,"minItems":1,"type":"array"}},"required":["urls","reason"],"type":"object"},"type":{"enum":["web_form"],"type":"string"}},"required":["type","owner"],"type":"object"},{"properties":{"file_urls":{"items":{"format":"uri","type":"string"},"maxItems":5,"minItems":1,"type":"array"},"keywords":{"items":{"maxLength":70,"pattern":"^[a-zA-Z0-9]+$","type":"string"},"maxItems":1,"type":"array"},"type":{"enum":["text"],"type":"string"}},"required":["type","file_urls"],"type":"object"},{"properties":{"file_urls":{"items":{"format":"uri","type":"string"},"maxItems":5,"minItems":1,"type":"array"},"type":{"enum":["paper_form"],"type":"string"}},"required":["type","file_urls"],"type":"object"}]},"maxItems":1,"minItems":1,"type":"array"},"description":{"description":"An explanation of how the toll-free number will be used.","maxLength":500,"minLength":40,"type":"string"},"includes":{"items":{"enum":["age_gated"],"type":"string"},"type":"array","uniqueItems":true},"message_samples":{"items":{"maxLength":1000,"type":"string"},"maxItems":1,"minItems":1,"type":"array"},"phone_number_id":{"description":"The toll-free phone number to register.","type":"string"},"privacy_policy_url":{"format":"uri","maxLength":255,"type":"string"},"terms_and_conditions_url":{"format":"uri","maxLength":255,"type":"string"},"use_cases":{"items":{"enum":["two_factor_authentication","account_notification","customer_care","charity","delivery_notification","fraud_alert","event","higher_education","k12_education","marketing","polling_voting","political","public_service_announcement","security_alert"],"type":"string"},"minItems":1,"type":"array"}},"required":["phone_number_id","use_cases","description","message_samples","privacy_policy_url","terms_and_conditions_url","consent_flows"],"title":"TollFreeCampaignParams","type":"object"},"MessageParams":{"description":"Payload for creating a message. Either an attachment or the body must be given. You can specify the recipient either using the 'conversation' parameter or the 'to'/'from' parameters, but not both.","example":{"attachments":[{"url":"https://toretto.family/coronas.gif"}],"body":"Thought you could leave without saying goodbye?","conversation":{"contact":{"first_name":"Dominic","last_name":"Toretto","phone_number":"+18015551234"}},"metadata":{"external_id":"12345"},"settings":{"link_shortening":"enabled"}},"oneOf":[{"description":"Create a message while including parameters for the conversation in which the message should be sent.","properties":{"attachments":{"items":{"$ref":"#/components/schemas/AttachmentParams"},"type":"array"},"body":{"description":"The message body.","type":"string"},"conversation":{"$ref":"#/components/schemas/ConversationParams"},"metadata":{"$ref":"#/components/schemas/Metadata"},"send_at":{"description":"An optional datetime for scheduling message up to a couple of months in the future.","format":"date-time","type":"string"},"settings":{"$ref":"#/components/schemas/MessageSettingsParams"}},"required":["conversation"],"title":"MessageParamsWithConversation","type":"object"},{"description":"Create a basic message by specifying just the to/from phone numbers.","properties":{"attachments":{"items":{"$ref":"#/components/schemas/AttachmentParams"},"type":"array"},"body":{"description":"The message body.","type":"string"},"from":{"description":"The sender's phone number in E.164 format or phone number ID. If omitted, uses the account's default phone number. Cannot be used together with 'conversation'.","example":"+18015552345","pattern":"^\\+[1-9]\\d{6,14}$|^\\d{5,6}$|^pn_[[:alnum:]]{26}$","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"send_at":{"description":"An optional datetime for scheduling message up to a couple of months in the future.","format":"date-time","type":"string"},"settings":{"$ref":"#/components/schemas/MessageSettingsParams"},"to":{"description":"The recipient's phone number in E.164 format. Cannot be used together with 'conversation'.","example":"+18015551234","format":"phone-number","pattern":"^\\+[1-9]\\d{6,14}$","type":"string"}},"required":["to"],"title":"SimpleMessageParams","type":"object"}],"title":"MessageParams","type":"object"},"MessageSettingsParams":{"description":"Per-message setting overrides.","example":{"link_shortening":"enabled"},"properties":{"link_shortening":{"description":"Override link shortening for this message.","enum":["enabled","disabled"],"type":"string"}},"title":"MessageSettingsParams","type":"object"},"PhoneNumberUpdateParams":{"description":"Updates a phone number's details.","example":{"campaign_id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2","metadata":{"location":"Downtown store"},"name":"Letty's Main Line"},"properties":{"campaign_id":{"description":"Campaign ID to attach this number to (`cpn_...`).","example":"cpn_01jjnn7s0zfx5tdcsxjfy93et2","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"description":"A human-readable name for the phone number.","example":"Letty's Main Line","type":"string"}},"required":[],"title":"PhoneNumberUpdateParams","type":"object"},"ErrorResponse":{"description":"An error response","example":{"error":{"message":"The requested resource could not be found.","type":"not_found"}},"properties":{"error":{"$ref":"#/components/schemas/Error"}},"required":["error"],"title":"ErrorResponse","type":"object"},"PhoneNumberPurchaseParams":{"description":"Parameters for purchasing a new phone number. The system will automatically infer the type in certain cases:\n- If only area_code is provided, type is inferred from the area code\n- If only latitude/longitude are provided, type is inferred as 'local'\n- Otherwise, type must be explicitly specified\n\nIf phone_number is provided, all other search parameters are ignored.\n","examples":[{"description":"Purchase any available local number","summary":"Random local number","value":{"type":"local"}},{"description":"Purchase any available toll-free number","summary":"Random toll-free number","value":{"type":"toll_free"}},{"description":"Purchase a number from area code 801","summary":"Number from area code","value":{"area_code":"801"}},{"description":"Purchase a local number near New York City","summary":"Local number near coordinates","value":{"latitude":40.7128,"longitude":-74.006}},{"description":"Purchase a specific phone number from inventory","summary":"Specific phone number","value":{"name":"Support Line","phone_number":"+18015551234"}}],"properties":{"area_code":{"description":"The desired area code for this phone number. If provided without type, the type will be inferred.","example":"801","pattern":"^\\d{3}$","type":"string"},"latitude":{"description":"Latitude to search for nearby phone numbers. Must be used with longitude. If provided without type, type will be inferred as 'local'.","example":40.7128,"maximum":90,"minimum":-90,"type":"number"},"longitude":{"description":"Longitude to search for nearby phone numbers. Must be used with latitude. If provided without type, type will be inferred as 'local'.","example":-74.006,"maximum":180,"minimum":-180,"type":"number"},"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"description":"A human-readable name for the phone number. If not provided, defaults to the formatted phone number.","example":"Support Line","type":"string"},"phone_number":{"description":"The exact phone number to purchase in E.164 format. When provided, all other search parameters are ignored.","example":"+18015551234","format":"phone-number","pattern":"^\\+[1-9]\\d{6,14}$","type":"string"},"type":{"description":"Whether the phone number is local or toll-free. Can be omitted if area_code or latitude/longitude are provided.","enum":["local","toll_free"],"example":"local","type":"string"}},"required":[],"title":"PhoneNumberPurchaseParams","type":"object"},"PhoneNumberImportedEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"campaign":{"attachment_status":"attachment_pending","id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2"},"campaign_id":"cpn_01jjnn7s0zfx5tdcsxjfy93et2","id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"name":"(801) 555-1234","number":"+18015551234","type":"local"},"timestamp":"2024-10-21T23:29:41Z","type":"phone_number.imported"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"campaign":{"description":"Campaign attachment details for this phone number","oneOf":[{"$ref":"#/components/schemas/PhoneNumberCampaign"},{"type":"null"}]},"campaign_id":{"deprecated":true,"description":"Deprecated. The unique identifier of the campaign this phone number is attached to","type":["string","null"],"x-stainless-deprecation-message":"Use `campaign.id` instead."},"id":{"description":"The unique identifier for the phone number","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"name":{"description":"A human-readable name for the phone number","type":["string","null"]},"number":{"description":"The phone number in E.164 format","type":"string"},"type":{"description":"Whether the phone number is local, toll-free, or short code","enum":["local","short_code","toll_free"],"type":"string"}},"required":["id","metadata","name","number","type","campaign","campaign_id"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"phone_number.imported","description":"The type of the event. Always `phone_number.imported` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"PhoneNumberImportedEvent","type":"object"},"StandardCampaignParams":{"description":"Full campaign details for standard registration through Surge","example":{"consent_flow":"When customers bring in their car for service, they will fill out this web form for intake: https://fastauto.shop/bp108c In it they can choose to opt in to text message notifications. If they choose to opt in, we will send them notifications to let them know if our mechanics find issues and once the car is ready to go, as well as links to invoices and to leave us feedback.","description":"This phone number will send auto maintenance notifications to end users that have opted in. It will also be used for responding to customer inquiries and sending some marketing offers.","includes":["links","phone_numbers"],"link_sample":"https://l.fastauto.shop/s034ij","message_samples":["You are now opted in to receive repair notifications from DT Precision Auto. Frequency varies. Msg&data rates apply. Reply STOP to opt out.","You're lucky that hundred shot of NOS didn't blow the welds on the intake!","Your car is ready to go. See your invoice here: https://l.fastauto.shop/s034ij"],"privacy_policy_url":"https://fastauto.shop/sms-privacy","terms_and_conditions_url":"https://fastauto.shop/terms-and-conditions","use_cases":["account_notification","customer_care","marketing"],"volume":"high"},"properties":{"consent_flow":{"description":"A string explaining the method through which end users will opt in to receive messages from the brand. Typically this should include URLs for opt-in forms or screenshots that might be helpful in explaining the flow to someone unfamiliar with the organization's purpose.","maxLength":4096,"minLength":40,"type":"string"},"description":{"description":"An explanation of the organization's purpose and how it will be using text messaging to accomplish that purpose.","maxLength":4096,"minLength":40,"type":"string"},"includes":{"description":"A list of properties that this campaign should include. These properties can be any of the following values:\n\n- `links` - whether the campaign might send links in messages\n- `phone_numbers` - whether the campaign might send phone numbers in messages\n- `age_gated` - whether the campaign contains age gated content (controlled substances or adult content)\n- `direct_lending` - whether the campaign contains content related to direct lending or other loan arrangements\n","items":{"enum":["links","phone_numbers","age_gated","direct_lending"],"type":"string"},"type":"array","uniqueItems":true},"link_sample":{"description":"A sample link that might be sent by this campaign. This is required when `includes` contains `links`. Provide the same URL or domain that the campaign will use in production. If links from other domains are sent through this campaign, they are much more likely to be filtered by the carriers.","format":"uri","maxLength":255,"type":"string"},"message_samples":{"description":"An array of 2-5 strings with examples of the messages that will be sent from this campaign. Typically the first sample should be a compliance message like `You are now opted in to messages from {brand name}. Frequency varies. Msg&data rates apply. Reply STOP to opt out.` These samples don't necessarily need to be the only templates that will be used for the campaign, but they should reflect the purpose of the messages that will be sent. Any variable content can be reflected by wrapping it in square brackets like `[customer name]`.","items":{"maxLength":1024,"minLength":20,"type":"string"},"maxItems":5,"minItems":2,"type":"array"},"privacy_policy_url":{"description":"The URL of the privacy policy for the brand in question. This may be a shared privacy policy if it's the policy that is displayed to end users when they opt in to messaging.","format":"uri","maxLength":255,"type":"string"},"terms_and_conditions_url":{"description":"The URL of the terms and conditions presented to end users when they opt in to messaging. These terms and conditions may be shared among all of a platform's customers if they're the terms that are presented to end users when they opt in to messaging.","format":"uri","maxLength":255,"type":"string"},"use_cases":{"description":"A list containing 1-5 types of messages that will be sent with this campaign.\n\nThe following use cases are typically available to all brands:\n\n- `account_notification` - For sending reminders, alerts, and general account-related notifications like booking confirmations or appointment reminders.\n- `customer_care` - For account support, troubleshooting, and general customer service communication.\n- `delivery_notification` - For notifying customers about the status of product or service deliveries.\n- `fraud_alert` - For warning customers about suspicious or potentially fraudulent activity.\n- `higher_education` - For messaging related to colleges, universities, and school districts outside of K–12.\n- `marketing` - For promotional or advertising messages intended to market products or services.\n- `polling_voting` - For conducting surveys, polls, or voting-related messaging.\n- `public_service_announcement` - For raising awareness about social issues or important public information.\n- `security_alert` - For alerts related to potential security breaches or compromised systems requiring user action.\n- `two_factor_authentication` - For sending one-time passwords or verification codes for login or password reset.\n\nFor access to special use cases not shown here, reach out to support@surge.app.\n","items":{"enum":["account_notification","customer_care","delivery_notification","fraud_alert","higher_education","marketing","polling_voting","public_service_announcement","security_alert","two_factor_authentication"],"type":"string"},"maxItems":5,"minItems":1,"type":"array"},"volume":{"description":"This will be one of the following:\n\n- `low` - The campaign will be allowed to send up to 2000 SMS segments to T-Mobile customers each day. In this case your platform will be charged for the setup fee for a low volume number upon receipt of the API request.\n- `high` - The campaign will be allowed to send up to 200k SMS segments to T-Mobile customers each day, depending on the trust score assigned by The Campaign Registry. Your platform will be charged for the setup fee for a high volume number upon receipt of the API request, and phone numbers will be charged as high volume numbers going forward.\n","enum":["high","low"],"type":"string"}},"required":["consent_flow","description","message_samples","privacy_policy_url","terms_and_conditions_url","use_cases","volume"],"title":"StandardCampaignParams","type":"object"},"Metadata":{"additionalProperties":{"maxLength":500,"type":"string"},"description":"Set of key-value pairs that will be stored with the object.","maxProperties":50,"properties":{},"title":"Metadata","type":"object"},"VerificationParams":{"description":"Parameters for creating a Verification","example":{"phone_number":"+18015551234"},"properties":{"phone_number":{"description":"The phone number to be verified. In E.164 format.","example":"+18015551234","format":"phone-number","pattern":"^\\+[1-9]\\d{6,14}$","type":"string"}},"required":["phone_number"],"title":"VerificationParams","type":"object"},"UserList":{"description":"A paginated list of users","properties":{"data":{"description":"The list of users","items":{"$ref":"#/components/schemas/User"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"title":"UserList","type":"object"},"Pagination":{"description":"Cursor-based pagination information","example":{"next_cursor":"g3QAAAABZAACaWRtAAAAGnBuXzAxamtzY2s5eDdkeW0wZnBxZjdjYmRyeQ==","previous_cursor":null},"properties":{"next_cursor":{"description":"Cursor for the next page of results. Null if there is no next page.","type":["string","null"]},"previous_cursor":{"description":"Cursor for the previous page of results. Null if there is no previous page.","type":["string","null"]}},"title":"Pagination","type":"object"},"Audience":{"description":"A group of contacts used for targeting messages.","example":{"id":"aud_01j9dy8mdzfn3r0e8x1tbdrdrf","name":"The Family"},"properties":{"id":{"description":"Unique identifier for the object.","type":"string"},"name":{"description":"A name to identify this Audience. This name will only be visible within Surge.","maxLength":255,"type":"string"}},"required":["id","name"],"title":"Audience","type":"object"},"Recording":{"description":"A call recording","example":{"call":{"contact":{"email":"dom@toretto.family","first_name":"Dominic","id":"ctc_01ja88cboqffhswjx8zbak3ykk","last_name":"Toretto","metadata":{"car":"1970 Dodge Charger R/T"},"phone_number":"+18015551234"},"duration":184,"id":"call_01jjnn7s0zfx5tdcsxjfy93et2","initiated_at":"2025-03-31T21:01:37Z","status":"completed"},"duration":124,"id":"rec_01kfyc9dgdec1avkgs7tng8htg"},"properties":{"call":{"description":"The call that produced this recording","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"duration":{"description":"The duration of the call in seconds","type":"integer"},"id":{"description":"The unique identifier for the call","type":"string"},"initiated_at":{"description":"When the call was initiated","format":"date-time","type":"string"},"status":{"description":"The status of the call","enum":["busy","canceled","completed","failed","in_progress","missed","no_answer","queued","ringing"],"type":"string"}},"required":["id","contact","duration","initiated_at","status"],"type":"object"},"duration":{"description":"The duration of the recording in seconds","type":"integer"},"id":{"description":"The unique identifier for the recording","type":"string"}},"required":["id","duration","call"],"title":"Recording","type":"object"},"ExternalCampaignParams":{"description":"Import an externally registered campaign from The Campaign Registry (TCR)","example":{"tcr_id":"CABCDE1"},"properties":{"tcr_id":{"description":"The Campaign Registry (TCR) ID for the externally registered campaign","example":"CABCDE1","maxLength":7,"minLength":7,"pattern":"^C[A-Z0-9]{6}$","type":"string"}},"required":["tcr_id"],"title":"ExternalCampaignParams","type":"object"},"MessageList":{"description":"A paginated list of messages","example":{"data":[{"attachments":[],"blast_id":null,"body":"Thought you could leave without saying goodbye?","conversation":{"contact":{"first_name":"Dominic","id":"ctc_01j9dy8mdzfn3r0e8x1tbdrdrf","last_name":"Toretto","phone_number":"+18015551234"},"id":"cnv_01j9e0dgmdfkj86c877ws0znae","phone_number":{"id":"pn_01jsjwe4d9fx3tpymgtg958d9w","metadata":{"location":"Downtown store"},"number":"+18015552345","type":"local"}},"id":"msg_01j9e0m1m6fc38gsv2vkfqgzz2","status":"delivered"}],"pagination":{"next_cursor":null,"previous_cursor":null}},"properties":{"data":{"description":"The list of messages","items":{"$ref":"#/components/schemas/Message"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"title":"MessageList","type":"object"},"CallEndedEvent":{"description":"","example":{"account_id":"acct_01japd271aeatb7txrzr2xj8sg","data":{"contact":{"email":"dom@toretto.family","first_name":"Dominic","id":"ctc_01ja88cboqffhswjx8zbak3ykk","last_name":"Toretto","metadata":{"car":"1970 Dodge Charger R/T"},"phone_number":"+18015551234"},"duration":184,"from":"+18015551234","id":"call_01jjnn7s0zfx5tdcsxjfy93et2","initiated_at":"2025-03-31T21:01:37Z","phone_number_id":"pn_01jsjwe4d9fx3tpymgtg958d9w","status":"completed","to":"+18015556789"},"timestamp":"2024-10-21T23:29:41Z","type":"call.ended"},"properties":{"account_id":{"description":"The ID of the account in which this event occurred","type":"string"},"data":{"description":"The data associated with the event","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"duration":{"description":"The duration of the call in seconds","type":"integer"},"from":{"description":"The E.164 phone number of the caller","type":["string","null"]},"id":{"description":"The unique identifier for the call","type":"string"},"initiated_at":{"description":"When the call was initiated","format":"date-time","type":"string"},"phone_number_id":{"description":"The Surge phone number ID (e.g. pn_...)","type":["string","null"]},"status":{"description":"The status of the call","enum":["busy","canceled","completed","failed","in_progress","missed","no_answer","queued","ringing"],"type":"string"},"to":{"description":"The E.164 phone number of the callee","type":["string","null"]}},"required":["id","contact","duration","initiated_at","status"],"type":"object"},"timestamp":{"description":"The timestamp when this event occurred, in ISO8601 format","format":"date-time","type":"string"},"type":{"const":"call.ended","description":"The type of the event. Always `call.ended` for this event.","type":"string"}},"required":["account_id","data","timestamp","type"],"title":"CallEndedEvent","type":"object"},"Contact":{"description":"A contact who has consented to receive messages","example":{"email":"dom@toretto.family","first_name":"Dominic","id":"ctc_01j9dy8mdzfn3r0e8x1tbdrdrf","last_name":"Toretto","metadata":{"car":"1970 Dodge Charger R/T"},"outbound_disabled":false,"phone_number":"+18015551234"},"properties":{"email":{"description":"The contact's email address.","format":"email","type":"string"},"first_name":{"description":"The contact's first name.","type":"string"},"id":{"description":"Unique identifier for the object.","type":"string"},"last_name":{"description":"The contact's last name.","type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"},"outbound_disabled":{"description":"Whether outbound messaging has been manually disabled for the contact.","type":"boolean"},"phone_number":{"description":"The contact's phone number in E.164 format.","example":"+18015551234","format":"phone-number","pattern":"^\\+[1-9]\\d{6,14}$","type":"string"}},"required":["id","phone_number"],"title":"Contact","type":"object"},"Campaign":{"description":"A campaign represents the context in which one or more of your phone numbers communicates with your contacts. Consent and opt-outs are tied to the campaign.","example":{"consent_flow":"When customers bring in their car for service, they will fill out this web form for intake: https://fastauto.shop/bp108c In it they can choose to opt in to text message notifications. If they choose to opt in, we will send them notifications to let them know if our mechanics find issues and once the car is ready to go, as well as links to invoices and to leave us feedback.","description":"This phone number will send auto maintenance notifications to end users that have opted in. It will also be used for responding to customer inquiries and sending some marketing offers.","id":"cpn_01k0qczvhbet4azgn5xm2ccfst","includes":["links","phone_numbers"],"link_sample":"https://l.fastauto.shop/s034ij","message_samples":["You are now opted in to receive repair notifications from DT Precision Auto. Frequency varies. Msg&data rates apply. Reply STOP to opt out.","You're lucky that hundred shot of NOS didn't blow the welds on the intake!","Your car is ready to go. See your invoice here: https://l.fastauto.shop/s034ij"],"privacy_policy_url":"https://fastauto.shop/sms-privacy","status":"pending","terms_and_conditions_url":"https://fastauto.shop/terms-and-conditions","use_cases":["account_notification","customer_care","marketing"],"volume":"high"},"properties":{"consent_flow":{"description":"A string explaining the method through which end users will opt in to receive messages from the brand. Typically this should include URLs for opt-in forms or screenshots that might be helpful in explaining the flow to someone unfamiliar with the organization's purpose.","maxLength":4096,"minLength":40,"type":"string"},"description":{"description":"An explanation of the organization's purpose and how it will be using text messaging to accomplish that purpose.","maxLength":4096,"minLength":40,"type":"string"},"id":{"description":"The campaign ID","type":"string"},"includes":{"description":"A list of properties that this campaign should include. These properties can be any of the following values:\n\n- `links` - whether the campaign might send links in messages\n- `phone_numbers` - whether the campaign might send phone numbers in messages\n- `age_gated` - whether the campaign contains age gated content (controlled substances or adult content)\n- `direct_lending` - whether the campaign contains content related to direct lending or other loan arrangements\n","items":{"enum":["links","phone_numbers","age_gated","direct_lending"],"type":"string"},"type":"array","uniqueItems":true},"link_sample":{"description":"A sample link that might be sent by this campaign. This is required when `includes` contains `links`. Provide the same URL or domain that the campaign will use in production. If links from other domains are sent through this campaign, they are much more likely to be filtered by the carriers.","format":"uri","maxLength":255,"type":"string"},"message_samples":{"description":"An array of 2-5 strings with examples of the messages that will be sent from this campaign. Typically the first sample should be a compliance message like `You are now opted in to messages from {brand name}. Frequency varies. Msg&data rates apply. Reply STOP to opt out.` These samples don't necessarily need to be the only templates that will be used for the campaign, but they should reflect the purpose of the messages that will be sent. Any variable content can be reflected by wrapping it in square brackets like `[customer name]`.","items":{"maxLength":1024,"minLength":20,"type":"string"},"maxItems":5,"minItems":2,"type":"array"},"privacy_policy_url":{"description":"The URL of the privacy policy for the brand in question. This may be a shared privacy policy if it's the policy that is displayed to end users when they opt in to messaging.","format":"uri","maxLength":255,"type":"string"},"status":{"description":"The current status of the campaign.","enum":["active","canceled","rejected","created","deactivated","in_review"],"type":"string"},"terms_and_conditions_url":{"description":"The URL of the terms and conditions presented to end users when they opt in to messaging. These terms and conditions may be shared among all of a platform's customers if they're the terms that are presented to end users when they opt in to messaging.","format":"uri","maxLength":255,"type":"string"},"use_cases":{"description":"A list containing 1-5 types of messages that will be sent with this campaign.\n\nThe following use cases are typically available to all brands:\n\n- `account_notification` - For sending reminders, alerts, and general account-related notifications like booking confirmations or appointment reminders.\n- `customer_care` - For account support, troubleshooting, and general customer service communication.\n- `delivery_notification` - For notifying customers about the status of product or service deliveries.\n- `fraud_alert` - For warning customers about suspicious or potentially fraudulent activity.\n- `higher_education` - For messaging related to colleges, universities, and school districts outside of K–12.\n- `marketing` - For promotional or advertising messages intended to market products or services.\n- `polling_voting` - For conducting surveys, polls, or voting-related messaging.\n- `public_service_announcement` - For raising awareness about social issues or important public information.\n- `security_alert` - For alerts related to potential security breaches or compromised systems requiring user action.\n- `two_factor_authentication` - For sending one-time passwords or verification codes for login or password reset.\n\nFor access to special use cases not shown here, reach out to support@surge.app.\n","items":{"enum":["account_notification","customer_care","delivery_notification","fraud_alert","higher_education","marketing","polling_voting","public_service_announcement","security_alert","two_factor_authentication"],"type":"string"},"maxItems":5,"minItems":1,"type":"array"},"volume":{"description":"This will be one of the following:\n\n- `low` - The campaign will be allowed to send up to 2000 SMS segments to T-Mobile customers each day. In this case your platform will be charged for the setup fee for a low volume number upon receipt of the API request.\n- `high` - The campaign will be allowed to send up to 200k SMS segments to T-Mobile customers each day, depending on the trust score assigned by The Campaign Registry. Your platform will be charged for the setup fee for a high volume number upon receipt of the API request, and phone numbers will be charged as high volume numbers going forward.\n","enum":["high","low"],"type":"string"}},"required":["consent_flow","description","id","includes","message_samples","privacy_policy_url","status","use_cases","volume"],"title":"Campaign","type":"object"}},"securitySchemes":{"authorization":{"bearerFormat":"Surge API token","scheme":"bearer","type":"http"}}},"info":{"title":"Surge","version":"1.0"},"jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","openapi":"3.1.1","paths":{"/accounts":{"get":{"description":"List all accounts for the calling platform with cursor-based pagination.","operationId":"ListAccounts","parameters":[{"in":"query","name":"after","required":false,"schema":{"description":"Cursor for forward pagination. Use the next_cursor from a previous response.","type":"string"}},{"in":"query","name":"before","required":false,"schema":{"description":"Cursor for backward pagination. Use the previous_cursor from a previous response.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountList"}}},"description":"List of accounts"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"List accounts","tags":["Accounts"]},"post":{"description":"Creates a new Account within the calling Platform.","operationId":"CreateAccount","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountParams"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}},"description":"Created account"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Create an account","tags":["Accounts"]}},"/accounts/{account_id}/audiences":{"post":{"description":"Creates a new audience.","operationId":"CreateAudience","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account for which the audience should be created.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceCreateParams"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Audience"}}},"description":"Created audience"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Create an audience","tags":["Audiences"]}},"/accounts/{account_id}/available_phone_numbers":{"get":{"description":"Browse purchasable phone numbers from Surge inventory before buying.\n\nPagination cursors are always null for now.\n","operationId":"ListAvailablePhoneNumbers","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account ID to list available phone numbers for.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}},{"in":"query","name":"area_code","required":false,"schema":{"description":"Filter by 3-digit area code.","example":"801","pattern":"^\\d{3}$","type":"string"}},{"in":"query","name":"country","required":false,"schema":{"description":"ISO country code to search in.","enum":["US","CA"],"example":"US","type":"string"}},{"in":"query","name":"type","required":true,"schema":{"description":"Whether to search for local or toll-free numbers.","enum":["local","toll_free"],"example":"local","type":"string"}},{"in":"query","name":"after","required":false,"schema":{"description":"Cursor for forward pagination. Use the next_cursor from a previous response.","type":"string"}},{"in":"query","name":"before","required":false,"schema":{"description":"Cursor for backward pagination. Use the previous_cursor from a previous response.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailablePhoneNumberList"}}},"description":"List of available phone numbers"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"List available phone numbers","tags":["Phone numbers"]}},"/accounts/{account_id}/blasts":{"post":{"description":"Sends a Blast.","operationId":"SendBlast","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account for which the blast should be sent.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlastParams"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Blast"}}},"description":"Created blast"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Send a blast","tags":["Blasts"]}},"/accounts/{account_id}/brand_verification_messages":{"post":{"description":"Enqueues an SMS OTP for a sole proprietor brand awaiting identity verification.","operationId":"ResendBrandVerificationMessage","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account whose brand verification OTP should be sent.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandVerificationMessageResponse"}}},"description":"Brand verification OTP send enqueued"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Resend brand verification OTP","tags":["Campaigns"]}},"/accounts/{account_id}/campaigns":{"get":{"description":"List all campaigns for an account with cursor-based pagination.","operationId":"ListCampaigns","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account ID to list campaigns for.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}},{"in":"query","name":"after","required":false,"schema":{"description":"Cursor for forward pagination. Use the next_cursor from a previous response.","type":"string"}},{"in":"query","name":"before","required":false,"schema":{"description":"Cursor for backward pagination. Use the previous_cursor from a previous response.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignList"}}},"description":"List of campaigns"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"List campaigns","tags":["Campaigns"]},"post":{"description":"Creates a campaign to register account to send text messages.","operationId":"CreateCampaign","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account for which the campaign should be created.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignParams"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}},"description":"Created campaign"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"External campaign already linked"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Create a campaign","tags":["Campaigns"]}},"/accounts/{account_id}/contacts":{"get":{"description":"List all contacts for an account with cursor-based pagination.","operationId":"ListContacts","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account ID to list contacts for.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}},{"in":"query","name":"after","required":false,"schema":{"description":"Cursor for forward pagination. Use the next_cursor from a previous response.","type":"string"}},{"in":"query","name":"before","required":false,"schema":{"description":"Cursor for backward pagination. Use the previous_cursor from a previous response.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"}}},"description":"List of contacts"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"List contacts","tags":["Contacts"]},"post":{"description":"Creates a new Contact object.","operationId":"CreateContact","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account for which the contact should be created.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactParams"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}},"description":"Created contact"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Create a contact","tags":["Contacts"]}},"/accounts/{account_id}/messages":{"get":{"description":"List all messages for an account with cursor-based pagination.","operationId":"ListMessages","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account ID to list messages for.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}},{"in":"query","name":"after","required":false,"schema":{"description":"Cursor for forward pagination. Use the next_cursor from a previous response.","type":"string"}},{"in":"query","name":"before","required":false,"schema":{"description":"Cursor for backward pagination. Use the previous_cursor from a previous response.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageList"}}},"description":"List of messages"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"List messages","tags":["Messages"]},"post":{"description":"Creates and enqueues a new message to be sent.\n\nMessages are always sent asynchronously. When you hit this endpoint, the message will be created within Surge's system and enqueued for sending, and then the id for the new message will be returned. When the message is actually sent, a `message.sent` webhook event will be triggered and sent to any webhook endpoints that you have subscribed to this event type. Then a `message.delivered` webhook event will be triggered when the carrier sends us a delivery receipt.\n\nBy default all messages will be sent immediately. If you would like to schedule sending for some time up to 60 days in the future, you can do that by providing a value for the `send_at` field. This should be formatted as an ISO8601 datetime like `2028-10-14T18:06:00Z`.\n\nYou must include either a `body` or `attachments` field (or both) in the request body. The `body` field should contain the text of the message you want to send, and the `attachments` field should be an array of objects with a `url` field pointing to the file you want to attach. Surge will download these files and send them as attachments in the message.\n\nYou can provide either a `conversation` object or a `to` field to specify the intended recipient of the message, but an error will be returned if both fields are provided. Similarly the `from` field cannot be used together with the `conversation` field, and `conversation.phone_number` should be specified instead.\n\nOptionally, you can pass a `settings` object to override account-level settings for this message. Currently the only supported setting is `link_shortening`, which accepts `\"enabled\"` or `\"disabled\"`.\n","operationId":"CreateMessage","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account from which the message should be sent.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageParams"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}},"description":"Created message"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Create a message","tags":["Messages"]}},"/accounts/{account_id}/phone_numbers":{"get":{"description":"List all phone numbers for an account with cursor-based pagination.","operationId":"ListPhoneNumbers","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account ID to list phone numbers for.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}},{"in":"query","name":"after","required":false,"schema":{"description":"Cursor for forward pagination. Use the next_cursor from a previous response.","type":"string"}},{"in":"query","name":"before","required":false,"schema":{"description":"Cursor for backward pagination. Use the previous_cursor from a previous response.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberList"}}},"description":"List of phone numbers"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"List phone numbers","tags":["Phone numbers"]},"post":{"description":"Purchase a new phone number for the account. You can specify an exact phone number, search criteria, or let the system select a random number.\n\nWhen `phone_number` is provided, all other search parameters are ignored.\n","operationId":"PurchasePhoneNumber","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account for which the phone number should be created.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberPurchaseParams"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumber"}}},"description":"Purchased phone number"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Purchase a phone number","tags":["Phone numbers"]}},"/accounts/{account_id}/recordings":{"get":{"description":"List all recordings for an account with cursor-based pagination.","operationId":"ListRecordings","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account ID to list recordings for.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}},{"in":"query","name":"after","required":false,"schema":{"description":"Cursor for forward pagination. Use the next_cursor from a previous response.","type":"string"}},{"in":"query","name":"before","required":false,"schema":{"description":"Cursor for backward pagination. Use the previous_cursor from a previous response.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordingList"}}},"description":"List of recordings"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"List recordings","tags":["Recordings"]}},"/accounts/{account_id}/status":{"get":{"description":"Check an account's status and capabilities","operationId":"CheckAccountStatus","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"ID of the account to check","example":"acct_01jpqjvfg9enpt7pyxd60pcmxj","type":"string"}},{"explode":false,"in":"query","name":"capabilities","required":false,"schema":{"description":"capabilities about which to check the status","example":"local_messaging","items":{"enum":["local_messaging","toll_free_messaging"],"type":"string"},"type":"array"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountStatus"}}},"description":"Account status"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Check account status","tags":["Accounts"]}},"/accounts/{account_id}/toll_free_campaigns":{"post":{"description":"Creates a toll-free campaign and submits it for Surge review.","operationId":"CreateTollFreeCampaign","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account for which the toll-free campaign should be created.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TollFreeCampaignParams"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TollFreeCampaign"}}},"description":"Created toll-free campaign"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Phone number already has a toll-free campaign"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Create a toll-free campaign","tags":["Toll-Free Campaigns"]}},"/accounts/{account_id}/users":{"get":{"description":"List all users for an account with cursor-based pagination.","operationId":"ListUsers","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account ID to list users for.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}},{"in":"query","name":"after","required":false,"schema":{"description":"Cursor for forward pagination. Use the next_cursor from a previous response.","type":"string"}},{"in":"query","name":"before","required":false,"schema":{"description":"Cursor for backward pagination. Use the previous_cursor from a previous response.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserList"}}},"description":"List of users"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"List users","tags":["Users"]},"post":{"description":"Creates a new User object.","operationId":"CreateUser","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account for which the user should be created.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserParams"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}},"description":"Created user"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Create a user","tags":["Users"]}},"/accounts/{account_id}/verifications":{"post":{"description":"Creates a new Verification for an account and sends the code to the given phone number.","operationId":"CreateVerification","parameters":[{"in":"path","name":"account_id","required":true,"schema":{"description":"The account to associate with the verification.","example":"acct_01j9a43avnfqzbjfch6pygv1td","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationParams"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}},"description":"Created verification"},"422":{"content":{"application/json":{"examples":{"Opted out":{"value":{"error":{"message":"This number has opted out of receiving verification messages. Send START to (801) 555-1234 to opt in again.","type":"opted_out"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Opted out"},"429":{"content":{"application/json":{"examples":{"Rate limited":{"value":{"error":{"message":"Too many codes have been sent to this number. Please wait 10 minutes and try again.","type":"destination_rate_limit"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limited"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Create a verification","tags":["Verifications"]}},"/accounts/{id}":{"delete":{"description":"Archives an account and releases all associated resources.\n\n**Warning**: This action will:\n- Release all phone numbers associated with the account\n- Deactivate all campaigns\n- Make the account unusable for sending messages\n\nThis operation is irreversible. If you need to send SMS in the future, you will need to re-register new phone numbers and campaigns.\n","operationId":"ArchiveAccount","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the account to archive.","example":"acct_01jpqjvfg9enpt7pyxd60pcmxj","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}},"description":"Archived account"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Archive an account","tags":["Accounts"]},"get":{"description":"Retrieves an Account object.","operationId":"GetAccount","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the account to retrieve.","example":"acct_01jpqjvfg9enpt7pyxd60pcmxj","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}},"description":"Account"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Retrieve an account","tags":["Accounts"]},"patch":{"description":"Updates an Account","operationId":"UpdateAccount","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID for the account to update.","example":"acct_01jpqjvfg9enpt7pyxd60pcmxj","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountUpdateParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}},"description":"Updated account"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Update an account","tags":["Accounts"]}},"/attachments/{attachment_id}/file":{"get":{"description":"Redirects to a signed URL where the attachment file can be downloaded. URL is short-lived, so redirect should be followed immediately.","operationId":"GetAttachmentFile","parameters":[{"in":"path","name":"attachment_id","required":true,"schema":{"description":"The ID of the attachment.","example":"att_01kfyc9dgdec1avkgs7tng8htg","type":"string"}}],"responses":{"302":{"content":{},"description":"Redirect to the attachment file","headers":{"Location":{"description":"Signed URL to download the attachment file","schema":{"format":"uri","type":"string"}}}},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Get attachment file","tags":["Messages"]}},"/audiences/{audience_id}/contacts":{"get":{"description":"List all contacts in an audience with cursor-based pagination. The account is inferred from the audience.","operationId":"ListAudienceContacts","parameters":[{"in":"path","name":"audience_id","required":true,"schema":{"description":"The audience ID to list contacts for.","example":"aud_01j9a43avnfqzbjfch6pygv1td","type":"string"}},{"in":"query","name":"after","required":false,"schema":{"description":"Cursor for forward pagination. Use the next_cursor from a previous response.","type":"string"}},{"in":"query","name":"before","required":false,"schema":{"description":"Cursor for backward pagination. Use the previous_cursor from a previous response.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"}}},"description":"List of contacts"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"List audience contacts","tags":["Audiences"]},"post":{"description":"Adds an existing contact to a manual audience.","operationId":"AddContactToAudience","parameters":[{"in":"path","name":"audience_id","required":true,"schema":{"description":"The audience ID to add the contact to.","example":"aud_01j9a43avnfqzbjfch6pygv1td","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceContactParams"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}},"description":"The contact, now a member of the audience"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Add a contact to an audience","tags":["Audiences"]}},"/campaigns/{id}":{"get":{"description":"Retrieves a Campaign object.","operationId":"GetCampaign","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the campaign to retrieve.","example":"cpn_01k0qczvhbet4azgn5xm2ccfst","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}},"description":"Campaign"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Retrieve a campaign","tags":["Campaigns"]},"patch":{"description":"Updates a campaign that has not yet been approved. This can be used to fix issues flagged during review and resubmit the campaign. Returns an error if the campaign is currently in review, has already been approved, or has been deactivated.","operationId":"UpdateCampaign","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the campaign to update.","example":"cpn_01k0qczvhbet4azgn5xm2ccfst","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}},"description":"Updated campaign"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Update a campaign","tags":["Campaigns"]}},"/contacts/{id}":{"get":{"description":"Retrieves a Contact object.","operationId":"GetContact","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the contact to retrieve.","example":"ctc_01j9dy8mdzfn3r0e8x1tbdrdrf","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}},"description":"Contact"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Retrieve a contact","tags":["Contacts"]},"patch":{"description":"Updates the specified contact by setting the values of the parameters passed. Any parameters not provided will be left unchanged.","operationId":"UpdateContact","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the contact to update.","example":"ctc_01j9dy8mdzfn3r0e8x1tbdrdrf","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}},"description":"Updated contact"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Update a contact","tags":["Contacts"]}},"/messages/{id}":{"get":{"description":"Retrieves a Message object.","operationId":"GetMessage","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the message to retrieve.","example":"msg_01j9e0m1m6fc38gsv2vkfqgzz2","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}},"description":"Message"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Retrieve a message","tags":["Messages"]}},"/phone_numbers/{id}":{"delete":{"description":"Releases a phone number from the account.","operationId":"ReleasePhoneNumber","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the phone number to release.","example":"pn_01j9a43avnfqzbjfch6pygv1td","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumber"}}},"description":"Released phone number"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Release a phone number","tags":["Phone numbers"]},"get":{"description":"Retrieves a PhoneNumber object.","operationId":"GetPhoneNumber","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the phone number to retrieve.","example":"pn_01jsjwe4d9fx3tpymgtg958d9w","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumber"}}},"description":"Phone number"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Retrieve a phone number","tags":["Phone numbers"]},"patch":{"description":"Updates a phone number's details.","operationId":"UpdatePhoneNumber","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the phone number to update.","example":"pn_01jsjwe4d9fx3tpymgtg958d9w","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberUpdateParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumber"}}},"description":"Updated phone number"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Update a phone number","tags":["Phone numbers"]}},"/recordings/{id}":{"delete":{"description":"Deletes a recording. The recording file will be removed from storage asynchronously.","operationId":"DeleteRecording","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the recording.","example":"rec_01kfyc9dgdec1avkgs7tng8htg","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recording"}}},"description":"Deleted recording"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Delete a recording","tags":["Recordings"]},"get":{"description":"Retrieves a Recording object.","operationId":"GetRecording","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the recording to retrieve.","example":"rec_01kfyc9dgdec1avkgs7tng8htg","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recording"}}},"description":"Recording"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Retrieve a recording","tags":["Recordings"]}},"/recordings/{recording_id}/file":{"get":{"description":"Redirects to a signed URL where the recording audio file can be downloaded. URL is short-lived, so redirect should be followed immediately.","operationId":"GetRecordingFile","parameters":[{"in":"path","name":"recording_id","required":true,"schema":{"description":"The ID of the recording.","example":"rec_01kfyc9dgdec1avkgs7tng8htg","type":"string"}}],"responses":{"302":{"content":{},"description":"Redirect to the recording file","headers":{"Location":{"description":"Signed URL to download the recording file","schema":{"format":"uri","type":"string"}}}},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Get recording file","tags":["Recordings"]}},"/users/{id}":{"delete":{"description":"Deletes a user.\n\nOnce a user has been deleted, they will no longer be permitted to access any\nof the embedded components. Attempting to access a deleted user will return\na 404 Not Found error.\n","operationId":"DeleteUser","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the user to delete.","example":"usr_01j9dwavghe1ttppewekjjkfrx","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}},"description":"Deleted user"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Delete a user","tags":["Users"]},"get":{"description":"Retrieves a User object.","operationId":"GetUser","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the user to retrieve.","example":"usr_01j9dwavghe1ttppewekjjkfrx","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}},"description":"User"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Retrieve a user","tags":["Users"]},"patch":{"description":"Updates an existing User object.","operationId":"UpdateUser","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the user to update.","example":"usr_01j9dwavghe1ttppewekjjkfrx","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}},"description":"Updated user"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Update a user","tags":["Users"]}},"/users/{user_id}/tokens":{"post":{"description":"Provides a mechanism for having Surge create a signed token for embeds instead of signing with your own signing key.","operationId":"CreateToken","parameters":[{"in":"path","name":"user_id","required":true,"schema":{"description":"The user for which the token represents authentication.","example":"usr_01jymgdfrpec2asc5m0z3a6fr9","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenParams"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}},"description":"Created token"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Create a signed user token","tags":["Tokens"]}},"/verifications/{id}/checks":{"post":{"description":"Checks the code against a verification.","operationId":"CheckVerification","parameters":[{"in":"path","name":"id","required":true,"schema":{"description":"The ID of the verification to check against.","example":"vfn_01jayh15c2f2xamftg0xpyq1nj","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationCheckParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationCheck"}}},"description":"Correct code"},"409":{"content":{"application/json":{"examples":{"Already verified":{"value":{"result":"already_verified"}}},"schema":{"$ref":"#/components/schemas/VerificationCheck"}}},"description":"Already verified"},"422":{"content":{"application/json":{"examples":{"Exhausted":{"value":{"result":"incorrect","verification":{"attempt_count":3,"id":"vfn_01jayh15c2f2xamftg0xpyq1nj","phone_number":"+18015551234","status":"exhausted"}}},"Expired":{"value":{"result":"expired","verification":{"attempt_count":0,"id":"vfn_01jayh15c2f2xamftg0xpyq1nj","phone_number":"+18015551234","status":"expired"}}},"Incorrect":{"value":{"result":"incorrect","verification":{"attempt_count":1,"id":"vfn_01jayh15c2f2xamftg0xpyq1nj","phone_number":"+18015551234","status":"pending"}}}},"schema":{"$ref":"#/components/schemas/VerificationCheck"}}},"description":"Check failed"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error"}},"summary":"Check a verification","tags":["Verifications"]}}},"security":[{"authorization":[]}],"servers":[{"url":"https://api.surge.app"}],"webhooks":{"callEnded":{"post":{"description":"The `call.ended` event is delivered whenever a call is completed between a Surge number you own and another phone number.","operationId":"callEnded","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallEndedEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"campaignApproved":{"post":{"description":"The `campaign.approved` event is delivered whenever a campaign is approved by all of the US carriers and able to start sending text messages.","operationId":"campaignApproved","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignApprovedEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"contactOptedIn":{"post":{"description":"The `contact.opted_in` event is delivered whenever a contact opts back in to receiving messages by sending a keyword message (START, YES, UNSTOP).","operationId":"contactOptedIn","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactOptedInEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"contactOptedOut":{"post":{"description":"The `contact.opted_out` event is delivered whenever a contact opts out of receiving messages by sending a keyword message (STOP, CANCEL, UNSUBSCRIBE, etc.).","operationId":"contactOptedOut","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactOptedOutEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"conversationCreated":{"post":{"description":"The `conversation.created` event is delivered whenever a new conversation is started with a contact. This could be when either the contact sends a message to your Surge number or when you create a conversation, whether by sending an initial message to the contact or by manually creating the conversation using the API.","operationId":"conversationCreated","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCreatedEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"linkFollowed":{"post":{"description":"The `link.followed` event is delivered when a contact first follows a shortened link that was included in a message sent from a Surge number. This event is only triggered on the first click of each link; subsequent clicks on the same link do not generate additional events.","operationId":"linkFollowed","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkFollowedEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"messageDelivered":{"post":{"description":"The `message.delivered` event is delivered whenever a message sent from a Surge number is successfully delivered to the recipient. When the message is sent from a short code or toll-free number, this means that the message arrived on the recipient's device. When sent from a local number, this means that the message was successfully handed off to the recipient's mobile carrier, but does not guarantee that it arrived on the recipient's device.","operationId":"messageDelivered","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDeliveredEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"messageFailed":{"post":{"description":"The `message.failed` event is delivered whenever a message sent from your Surge number fails to be delivered.","operationId":"messageFailed","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageFailedEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"messageReceived":{"post":{"description":"The `message.received` event is delivered whenever a message is received at a Surge number from a contact.","operationId":"messageReceived","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageReceivedEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"messageSent":{"post":{"description":"The `message.sent` event is delivered whenever a message is sent from a Surge number to a contact.","operationId":"messageSent","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageSentEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"phoneNumberAttachedToCampaign":{"post":{"description":"The `phone_number.attached_to_campaign` event is delivered whenever a phone number is attached to a campaign.","operationId":"phoneNumberAttachedToCampaign","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberAttachedToCampaignEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"phoneNumberImported":{"post":{"description":"The `phone_number.imported` event is delivered whenever a phone number is imported into Surge from an external provider.","operationId":"phoneNumberImported","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberImportedEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"recordingCompleted":{"post":{"description":"The `recording.completed` event is delivered whenever a call recording has been processed and is ready for playback. This event is not triggered for voicemail recordings.","operationId":"recordingCompleted","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordingCompletedEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}},"voicemailReceived":{"post":{"description":"The `voicemail.received` event is delivered whenever a voicemail recording has been processed and is ready for playback.","operationId":"voicemailReceived","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoicemailReceivedEvent"}}}},"responses":{"200":{"description":"Return a 200 status to indicate that the data was received successfully"}}}}}}