From 11d42efa51653eba8b89dbf6ac13569088d72438 Mon Sep 17 00:00:00 2001 From: Theo Mathieu Date: Fri, 10 May 2024 09:05:21 +0200 Subject: [PATCH] chore: fix release please --- .gitignore | 4 +- release-please-config.json | 2 +- src/chargify.json | 23631 ------ src/openapi.json | 1999 - src/petstore-v3.1.json | 178 - src/sendgrid.json | 46080 ----------- src/stripe.json | 143117 ---------------------------------- 7 files changed, 4 insertions(+), 215007 deletions(-) delete mode 100644 src/chargify.json delete mode 100644 src/openapi.json delete mode 100644 src/petstore-v3.1.json delete mode 100644 src/sendgrid.json delete mode 100644 src/stripe.json diff --git a/.gitignore b/.gitignore index 10813de..db898dd 100644 --- a/.gitignore +++ b/.gitignore @@ -11,4 +11,6 @@ vite.config.ts.timestamp-* openapi.db dist -openapi.json \ No newline at end of file +openapi.json + +openapi-files \ No newline at end of file diff --git a/release-please-config.json b/release-please-config.json index 7de0174..1478309 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -1,7 +1,7 @@ { "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", "packages": { - "./": { + ".": { "release-type": "node", "changelog-path": "CHANGELOG.md" } diff --git a/src/chargify.json b/src/chargify.json deleted file mode 100644 index dde361f..0000000 --- a/src/chargify.json +++ /dev/null @@ -1,23631 +0,0 @@ -{ - "openapi": "3.1.0", - "info": { - "title": "Maxio Advanced Billing", - "version": "1.0", - "contact": { - "email": "support@chargify.com" - }, - "description": "## Introduction\n\n### API Integration\n\nMaxio Advanced Billing (formerly Chargify API) can be integrated with many environments and programming languages via our REST API. Some of our users have contributed their API wrappers in various programming languages. Check out the [API Code Overview](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDI2-api-code-samples) doc for an introduction to the wrappers and available code samples.\n\n### Testing Guide\n\nMaxio Advanced Billing has compiled a [testing guide](https://chargify.zendesk.com/hc/en-us/articles/4407904658587) that covers a list of important factors to consider while in the testing phase. Here's a high-level overiew of what's covered in our testing guide:\n\n+ Test credit card basics\n+ Test site limits\n+ Live mode versus test mode\n\nWe strongly suggest reading over the testing guide, as well as the entire set of application-based documentation to aid in your discovery of the product.\n\n### Engage Support\n\nWe always enjoy (and appreciate) hearing about larger integrations ahead of time. If you’re planning on importing a large amount of data into Maxio via our API, we suggest sending a “heads up” to “support@chargify.com” so we can coordinate with you to ensure your import process goes smoothly.\n\nOur API, while considered stable, is continually being improved and polished. Please feel free to contact support if you experience issues when integrating with the Maxio Advanced Billing API.\n\nIf you have any additional questions regarding our documentation please don't hesitate in reaching out.\n\n### Support Access\n\nAccess to our Technical Specialist team for API support is currently limited to purchasers of our larger Maxio support plans.\n\nBut don’t worry! There are quite a few options to help you get the answers you need:\n\n- [Read our documentation for developers](https://developers.chargify.com/docs/developer-docs/ZG9jOjM0NjA3MQ-overview)\n- Explore the endpoints of our API Documentation\n- [Watch our videos and tutorials](https://chargify.com/tutorials)\n- [Check out the Chargify tag on Stack Overflow](http://stackoverflow.com/questions/tagged/chargify)\n\n## API Overview\n\nThe Chargify API allows you to interact with our system programmatically from your own application. Using the API you interact with Resources such as:\n\n- Products\n- Subscriptions\n- Customers\n- etc.\n\nThe API attempts to conform to the [RESTful](http://en.wikipedia.org/wiki/Representational_State_Transfer) design principles.\nYou interact with the resources exposed via the API by accessing resource collection and element URIs using the HTTP verbs (GET, POST, PUT, and DELETE).\nChargify accepts and returns both JSON and XML data via the API.\n\nYou’ll likely need access to a web developer or programmer (if you’re not one) to get the most use out of the API.\n\n### Available Formats: JSON and XML\n\nJSON is the primary and recommended format for use with the Chargify API. XML is also provided as a backwards compatible option for Merchants who require it.\n\n### Authentication\n\nAuthentication is implemented as HTTP Basic Authentication over TLS >= 1.2 (HTTPS), as described in [API Authentication](https://developers.chargify.com/docs/developer-docs/ZG9jOjE1NTUxNQ-authentication)\n\n### URL\n\nThe URL for API requests includes the subdomain of the Site you are working with:\n\n`https://.chargify.com/`\n\n### Response Data\n\nResponse data is sent as either XML or JSON, depending on the type of data requested (`HTTP Content-Type` header) or the type specified as being accepted (HTTP `Accept` header).\n\nGETs for individual statements & invoices may also be requested as PDF using `application/pdf` or appending `.pdf` to the resource URI.\n\nResponse codes are sent via the normal HTTP Response Code, and are documented separately for each resource.\n\nFor boolean fields, please note that a value of `null` may be considered as false. However, this is not true across all cases. Please excercise good judgement here, or contact support with any questions.\n\nFor example:\n\n+ `null` can define that there's no data available for that attribute\n\n### Pagination\n\nWhen an endpoint returns a list of items, it will be paginated. Usually, 20 items will be returned by default, and you may request up to a maximum of 200 at a time. Pagination is done with query string parameters, for example: `?page=5&per_page=200`\n\n### Response Time Zones\n\nAPI responses from Chargify are sent with the timezone of current Chargify site.\n\nAlternately, webhooks sent from Chargify globally utilize EST as the timezone for all content in the body of the payload.\n\n### Request Data\n\nPOST and PUT request data may be formatted as either XML (`application/xml`) or JSON (`application/json`). For best results, you should set your HTTP `Content-Type` request header accordingly, although you may also specify your format by appending `.xml` or `.json` extensions on to the resource URI.\n\nNote that Chargify does not accept PUT or POST data sent as query params or form encoded data – data must be sent as either XML or JSON. If you fail to set your `Content-Type` to either `application/xml` or `application/json`, your request may fail due to triggering of forgery protection mechanisms.\n\n#### About Decimal Numbers\n\nIn order to prevent losing precision, we serialize decimal numbers as strings instead of as JSON numbers.\n\nWe recommend parsing these strings into their decimal equivalent using a decimal number library in your programming language (i.e. `BigDecimal` in Ruby) instead of relying on floating point values or arithmetic.\n\n#### About Amount Fields\n\nFields holding amount values are given as a string representing a decimal whole currency amount.\n\nFor example, `\"1.23\"` in currency `\"USD\"` would equate to `$1.23`.\n\nNot all fields will be rounded to the smallest currency denomination. Intermediate results, such as those that derive from line-level tax calculations, may hold precision up to 8 decimal places. However, the top-level totals we provide (e.g. `total_amount`) will be rounded to the smallest currency denomination.\n\nIt is up to API consumers to parse the string into a decimal number representation and do any rounding necessary for your application.\n\n### Debugging\n\nIf you’re having difficulty executing a request via our API, try the simplest thing and attempt your request via the curl command-line tool, as shown in the below example. Add the `--verbose` flag to your request to receive even more debugging information.\n\nAnother handy tool is [Beeceptor](https://beeceptor.com/). You can use this to intercept your request to see exactly what is being sent.\n\nIf you are unable to connect at all, check that you are using TLS 1.2 or better.\n\nIf you see a \"Could not resolve host\" error, double check that the url is correct, including your subdomain. For example: `mysite.chargify.com`. This error means your DNS server could not find an IP address for the domain you are trying to connect to.\n\n### Backwards Compatibility\n\nWe consider the following changes to be backwards compatible and may make them without advance notice:\n\n+ Adding new API endpoints, or adding new attributes in the responses of existing endpoints\n+ Adding new optional parameters to be sent to existing API endpoints\n+ Adding new fields to exported data\n+ Changing the type or length of any of the ID attributes\n + For example, most IDs are currently integers, but you should not assume that this will always be the case.\n\nIn addition, you should not depend on the order of attributes within the API response as this may change.\n\nChargify does not provide notifications for additions that are clearly defined as backwards compatible.\n\n### Examples\n\nThe following examples use the curl command-line tool to execute API requests.\n\n#### Subscription Listing\n\n**Request**\n\n curl -u :x -H Accept:application/json -H Content-Type:application/json https://acme.chargify.com/subscriptions.json\n\n\n## API Access Limitations\n\nThere are a few scenarios that may end up in causing an API request to be blocked even with correct credentials.\n**Please note:** All relevant API requests will be blocked if any of the below conditions are true. These limitations also apply to [Chargify Direct](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDE3-introduction).\n\nThose scenarios are as follows:\n\n- Your Chargify subscription is canceled.\n- Your Chargify trial has reached an end.\n- The site you're making a request for is in the process of [\"clearing site data\"](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405428327309)\n - _Note: any API request for another site that is in a good state will NOT be blocked_\n- The site you're making a request for has been deleted.\n - _Note: any API request for another site that is in a good state will NOT be blocked_\n\nRead more about your Chargify subscription [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405430043149-Advanced-Billing-Subscription#advanced-billing-subscription-0-0)\n\n### What happens when an API request is blocked\n\nThe request will fail with a `422` http status code. The response will also include a message explaining the reason for the request being blocked. For example:\n\n- If your Chargify subscription is canceled:\n\n```json\n{\n \"errors\" => [\n [0] \"Your Chargify account has been canceled. Please contact support@chargify.com to reactivate.\"\n ]\n}\n```\n\n- If your Chargify trial has reached and end and you attempted to make an API request, the response body will look like:\n\n```json\n{\n \"errors\" => [\n [0] \"Your trial has ended, please contact sales.\"\n ]\n}\n```\n\n- If the site you're making a request for is in the process of [\"clearing site data\"](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405428327309):\n\n```json\n{\n \"errors\" => [\n [0] \"Site data clearing is in progress. Please try later.\"\n ]\n}\n```\n\n- If the site you're making a request for has been deleted:\n\n```json\n{\n \"errors\" => [\n [0] \"This site has been deleted.\"\n ]\n}\n```\n\n## Secure Applications\n\nPlease note that it is NOT possible to make API requests directly from the customer's browser or device. Doing so would expose your API key on the client side, and anyone who has that key has full access to all of your Chargify data.\n\nInstead you will need to take care to tokenize sensitive information by using [Chargify.js](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDI0-overview) or a similar JavaScript library provided by your gateway, and then post the token and other information to your own server, from which you can make the API call to Chargify.\n\n#### Troubleshooting\n\nIf you attempt to make a Chargify API request directly from the customer's browser, you may see an error such as:\n\n```\nResponse to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.\n```\n\nor\n\n```\nOrigin 'https://example.com' is therefore not allowed access.` `The response had HTTP status code 404.\n```\n\nThis is an error message indicating that Cross-Origin Resource Sharing (CORS) is not enabled on the Chargify server.\n\n## Relationship Invoicing\n\n### API Compatibility for Relationship Invoicing\n\nThis section describes the API for the new, [Relationship Invoicing](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405078794253) style of invoices introduced in January 2018.\n\nIf you are an existing customer from prior to January 2018 or have not otherwise explicitly opted into this new style of invoices, you are probably looking for the legacy \"Invoices\" section that describes [invoice-billing legacy-style invoices](./b3A6MTQxMDgzNjQ-read-invoice).\n\nThese new invoices provide a single representation of all of your Chargify billing, whether you collect automatically or via remittance.\n\n### About Decimal Numbers\n\nIn order to prevent losing precision, we serialize decimal numbers as strings instead of as JSON numbers.\n\nWe recommend parsing these strings into their decimal equivalent using a decimal number library in your programming language (i.e. `BigDecimal` in Ruby) instead of relying on floating point values or arithmetic.\n\n### About Amount Fields\n\nFields holding amount values are given as a string representing a decimal whole currency amount.\n\nFor example, `\"1.23\"` in currency `\"USD\"` would equate to `$1.23`.\n\nNot all fields will be rounded to the smallest currency denomination. Intermediate results, such as those that derive from line-level tax calculations, may hold precision up to 8 decimal places. However, the top-level totals we provide (e.g. `total_amount`) will be rounded to the smallest currency denomination.\n\nIt is up to API consumers to parse the string into a decimal number representation and do any rounding necessary for your application.\n\n#### Relationship Invoicing Summary\n\n+ If your site **is** using relationship invoicing, you may only use the methods described in this section for working with invoices.\n\n+ If your site is **not** using relationship invoicing, please use the legacy invoice methods:\n\n + [Invoices](./b3A6MTQxMTA0MTA-read-invoice)\n + [Invoices: Payments](./b3A6MTQxMTA0MTI-create-invoice-payment)\n + [Invoices: Charges](./b3A6MTQxMTA0MTM-create-charge)\n + [Invoices: Credits](./b3A6MTQxMTA0MTQ-create-invoice-credit)" - }, - "tags": [ - { - "name": "API Exports" - }, - { - "name": "Advance Invoice" - }, - { - "name": "Billing Portal" - }, - { - "name": "Coupons" - }, - { - "name": "Components" - }, - { - "name": "Customers" - }, - { - "name": "Custom Fields" - }, - { - "name": "Events" - }, - { - "name": "Events-Based Billing: Segments" - }, - { - "name": "Insights" - }, - { - "name": "Invoices" - }, - { - "name": "Offers" - }, - { - "name": "Payment Profiles" - }, - { - "name": "Product Families" - }, - { - "name": "Products" - }, - { - "name": "Product: Price Points" - }, - { - "name": "Proforma Invoices" - }, - { - "name": "Reason Codes" - }, - { - "name": "Referral Codes" - }, - { - "name": "Sales Commissions" - }, - { - "name": "Sites" - }, - { - "name": "Subscriptions" - }, - { - "name": "Subscription Components" - }, - { - "name": "Subscription Groups" - }, - { - "name": "Subscription Group Invoice Account" - }, - { - "name": "Subscription Group Status" - }, - { - "name": "Subscription Invoice Account" - }, - { - "name": "Subscription Notes" - }, - { - "name": "Subscription Products" - }, - { - "name": "Subscription Status" - }, - { - "name": "Webhooks" - } - ], - "paths": { - "/webhooks.json": { - "get": { - "summary": "List Webhooks", - "tags": [ - "Webhooks" - ], - "responses": { - "201": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Webhook-Response.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "webhook": { - "event": "statement_settled", - "id": 141765032, - "created_at": "2016-11-08T16:22:26-05:00", - "last_error": "404 Resource Not Found (retry 5 of 5)", - "last_error_at": "2016-11-08T16:43:54-05:00", - "accepted_at": null, - "last_sent_at": "2016-11-08T16:43:54-05:00", - "last_sent_url": "http://requestb.in/11u45x71", - "successful": false, - "body": "id=141765032&event=statement_settled&payload[site][id]=31615&payload[site][subdomain]=general-goods&payload[subscription][id]=15100141&payload[subscription][state]=active&payload[subscription][balance_in_cents]=0&payload[customer][id]=14585695&payload[customer][first_name]=Pookie&payload[customer][last_name]=Test&payload[customer][reference]=&payload[customer][organization]=&payload[customer][address]=&payload[customer][address_2]=&payload[customer][city]=&payload[customer][state]=&payload[customer][zip]=&payload[customer][country]=&payload[customer][email]=pookie999%40example.com&payload[customer][phone]=&payload[statement][closed_at]=2016-11-08%2016%3A22%3A20%20-0500&payload[statement][created_at]=2016-11-08%2016%3A22%3A18%20-0500&payload[statement][id]=80168049&payload[statement][opened_at]=2016-11-07%2016%3A22%3A15%20-0500&payload[statement][settled_at]=2016-11-08%2016%3A22%3A20%20-0500&payload[statement][subscription_id]=15100141&payload[statement][updated_at]=2016-11-08%2016%3A22%3A20%20-0500&payload[statement][starting_balance_in_cents]=0&payload[statement][ending_balance_in_cents]=0&payload[statement][total_in_cents]=6400&payload[statement][memo]=We%20thank%20you%20for%20your%20continued%20business!&payload[statement][events][0][id]=346956565&payload[statement][events][0][key]=renewal_success&payload[statement][events][0][message]=Successful%20renewal%20for%20Pookie%20Test's%20subscription%20to%20%2410%20Basic%20Plan&payload[statement][events][1][id]=346956579&payload[statement][events][1][key]=payment_success&payload[statement][events][1][message]=Successful%20payment%20of%20%2464.00%20for%20Pookie%20Test's%20subscription%20to%20%2410%20Basic%20Plan&payload[statement][events][2][id]=347299359&payload[statement][events][2][key]=renewal_success&payload[statement][events][2][message]=Successful%20renewal%20for%20Pookie%20Test's%20subscription%20to%20%2410%20Basic%20Plan&payload[statement][transactions][0][id]=161537343&payload[statement][transactions][0][subscription_id]=15100141&payload[statement][transactions][0][type]=Charge&payload[statement][transactions][0][kind]=baseline&payload[statement][transactions][0][transaction_type]=charge&payload[statement][transactions][0][success]=true&payload[statement][transactions][0][amount_in_cents]=1000&payload[statement][transactions][0][memo]=%2410%20Basic%20Plan%20(11%2F08%2F2016%20-%2011%2F09%2F2016)&payload[statement][transactions][0][created_at]=2016-11-08%2016%3A22%3A18%20-0500&payload[statement][transactions][0][starting_balance_in_cents]=0&payload[statement][transactions][0][ending_balance_in_cents]=1000&payload[statement][transactions][0][gateway_used]=&payload[statement][transactions][0][gateway_transaction_id]=&payload[statement][transactions][0][gateway_order_id]=&payload[statement][transactions][0][payment_id]=161537369&payload[statement][transactions][0][product_id]=3792003&payload[statement][transactions][0][tax_id]=&payload[statement][transactions][0][component_id]=&payload[statement][transactions][0][statement_id]=80168049&payload[statement][transactions][0][customer_id]=14585695&payload[statement][transactions][0][original_amount_in_cents]=&payload[statement][transactions][0][discount_amount_in_cents]=&payload[statement][transactions][0][taxable_amount_in_cents]=&payload[statement][transactions][1][id]=161537344&payload[statement][transactions][1][subscription_id]=15100141&payload[statement][transactions][1][type]=Charge&payload[statement][transactions][1][kind]=quantity_based_component&payload[statement][transactions][1][transaction_type]=charge&payload[statement][transactions][1][success]=true&payload[statement][transactions][1][amount_in_cents]=5400&payload[statement][transactions][1][memo]=Timesheet%20Users%3A%2018%20Timesheet%20Users&payload[statement][transactions][1][created_at]=2016-11-08%2016%3A22%3A18%20-0500&payload[statement][transactions][1][starting_balance_in_cents]=1000&payload[statement][transactions][1][ending_balance_in_cents]=6400&payload[statement][transactions][1][gateway_used]=&payload[statement][transactions][1][gateway_transaction_id]=&payload[statement][transactions][1][gateway_order_id]=&payload[statement][transactions][1][payment_id]=161537369&payload[statement][transactions][1][product_id]=3792003&payload[statement][transactions][1][tax_id]=&payload[statement][transactions][1][component_id]=277221&payload[statement][transactions][1][statement_id]=80168049&payload[statement][transactions][1][customer_id]=14585695&payload[statement][transactions][1][original_amount_in_cents]=&payload[statement][transactions][1][discount_amount_in_cents]=&payload[statement][transactions][1][taxable_amount_in_cents]=&payload[statement][transactions][2][id]=161537369&payload[statement][transactions][2][subscription_id]=15100141&payload[statement][transactions][2][type]=Payment&payload[statement][transactions][2][kind]=&payload[statement][transactions][2][transaction_type]=payment&payload[statement][transactions][2][success]=true&payload[statement][transactions][2][amount_in_cents]=6400&payload[statement][transactions][2][memo]=Pookie%20Test%20-%20%2410%20Basic%20Plan%3A%20Renewal%20payment&payload[statement][transactions][2][created_at]=2016-11-08%2016%3A22%3A20%20-0500&payload[statement][transactions][2][starting_balance_in_cents]=6400&payload[statement][transactions][2][ending_balance_in_cents]=0&payload[statement][transactions][2][gateway_used]=bogus&payload[statement][transactions][2][gateway_transaction_id]=53433&payload[statement][transactions][2][gateway_order_id]=&payload[statement][transactions][2][payment_id]=&payload[statement][transactions][2][product_id]=3792003&payload[statement][transactions][2][tax_id]=&payload[statement][transactions][2][component_id]=&payload[statement][transactions][2][statement_id]=80168049&payload[statement][transactions][2][customer_id]=14585695&payload[statement][transactions][2][card_number]=XXXX-XXXX-XXXX-1&payload[statement][transactions][2][card_expiration]=10%2F2020&payload[statement][transactions][2][card_type]=bogus&payload[statement][transactions][2][refunded_amount_in_cents]=0&payload[product][id]=3792003&payload[product][name]=%2410%20Basic%20Plan&payload[product_family][id]=527890&payload[product_family][name]=Acme%20Projects&payload[payment_profile][id]=10102821&payload[payment_profile][first_name]=Pookie&payload[payment_profile][last_name]=Test&payload[payment_profile][billing_address]=&payload[payment_profile][billing_address_2]=&payload[payment_profile][billing_city]=&payload[payment_profile][billing_country]=&payload[payment_profile][billing_state]=&payload[payment_profile][billing_zip]=&payload[event_id]=347299384", - "signature": "7c606ec4628ce75ec46e284097ce163a", - "signature_hmac_sha_256": "40f25e83dd324508bb2149e3e525821922fb210535ebfbfa81e7ab951996b41d" - } - }, - { - "webhook": { - "event": "payment_success", - "id": 141765008, - "created_at": "2016-11-08T16:22:25-05:00", - "last_error": "404 Resource Not Found (retry 5 of 5)", - "last_error_at": "2016-11-08T16:43:54-05:00", - "accepted_at": null, - "last_sent_at": "2016-11-08T16:43:54-05:00", - "last_sent_url": "http://requestb.in/11u45x71", - "successful": false, - "body": "id=141765008&event=payment_success&payload[site][id]=31615&payload[site][subdomain]=general-goods&payload[subscription][id]=15100141&payload[subscription][state]=active&payload[subscription][trial_started_at]=&payload[subscription][trial_ended_at]=&payload[subscription][activated_at]=2016-11-04%2017%3A06%3A43%20-0400&payload[subscription][created_at]=2016-11-04%2017%3A06%3A42%20-0400&payload[subscription][updated_at]=2016-11-08%2016%3A22%3A22%20-0500&payload[subscription][expires_at]=&payload[subscription][balance_in_cents]=0&payload[subscription][current_period_ends_at]=2016-11-09%2016%3A06%3A42%20-0500&payload[subscription][next_assessment_at]=2016-11-09%2016%3A06%3A42%20-0500&payload[subscription][canceled_at]=&payload[subscription][cancellation_message]=&payload[subscription][next_product_id]=&payload[subscription][cancel_at_end_of_period]=false&payload[subscription][payment_collection_method]=automatic&payload[subscription][snap_day]=&payload[subscription][cancellation_method]=&payload[subscription][current_period_started_at]=2016-11-08%2016%3A06%3A42%20-0500&payload[subscription][previous_state]=active&payload[subscription][signup_payment_id]=161034048&payload[subscription][signup_revenue]=64.00&payload[subscription][delayed_cancel_at]=&payload[subscription][coupon_code]=&payload[subscription][total_revenue_in_cents]=32000&payload[subscription][product_price_in_cents]=1000&payload[subscription][product_version_number]=7&payload[subscription][payment_type]=credit_card&payload[subscription][referral_code]=pggn84&payload[subscription][coupon_use_count]=&payload[subscription][coupon_uses_allowed]=&payload[subscription][customer][id]=14585695&payload[subscription][customer][first_name]=Test&payload[subscription][customer][last_name]=Test&payload[subscription][customer][organization]=&payload[subscription][customer][email]=pookie999%40example.com&payload[subscription][customer][created_at]=2016-11-04%2017%3A06%3A42%20-0400&payload[subscription][customer][updated_at]=2016-11-04%2017%3A06%3A45%20-0400&payload[subscription][customer][reference]=&payload[subscription][customer][address]=&payload[subscription][customer][address_2]=&payload[subscription][customer][city]=&payload[subscription][customer][state]=&payload[subscription][customer][zip]=&payload[subscription][customer][country]=&payload[subscription][customer][phone]=&payload[subscription][customer][portal_invite_last_sent_at]=2016-11-04%2017%3A06%3A45%20-0400&payload[subscription][customer][portal_invite_last_accepted_at]=&payload[subscription][customer][verified]=false&payload[subscription][customer][portal_customer_created_at]=2016-11-04%2017%3A06%3A45%20-0400&payload[subscription][customer][cc_emails]=&payload[subscription][product][id]=3792003&payload[subscription][product][name]=%2410%20Basic%20Plan&payload[subscription][product][handle]=basic&payload[subscription][product][description]=lorem%20ipsum&payload[subscription][product][accounting_code]=basic&payload[subscription][product][request_credit_card]=false&payload[subscription][product][expiration_interval]=&payload[subscription][product][expiration_interval_unit]=never&payload[subscription][product][created_at]=2016-03-24%2013%3A38%3A39%20-0400&payload[subscription][product][updated_at]=2016-11-03%2013%3A03%3A05%20-0400&payload[subscription][product][price_in_cents]=1000&payload[subscription][product][interval]=1&payload[subscription][product][interval_unit]=day&payload[subscription][product][initial_charge_in_cents]=&payload[subscription][product][trial_price_in_cents]=&payload[subscription][product][trial_interval]=&payload[subscription][product][trial_interval_unit]=month&payload[subscription][product][archived_at]=&payload[subscription][product][require_credit_card]=false&payload[subscription][product][return_params]=&payload[subscription][product][taxable]=false&payload[subscription][product][update_return_url]=&payload[subscription][product][initial_charge_after_trial]=false&payload[subscription][product][version_number]=7&payload[subscription][product][update_return_params]=&payload[subscription][product][product_family][id]=527890&payload[subscription][product][product_family][name]=Acme%20Projects&payload[subscription][product][product_family][description]=&payload[subscription][product][product_family][handle]=billing-plans&payload[subscription][product][product_family][accounting_code]=&payload[subscription][product][public_signup_pages][id]=281054&payload[subscription][product][public_signup_pages][return_url]=http%3A%2F%2Fwww.example.com%3Fsuccessfulsignup&payload[subscription][product][public_signup_pages][return_params]=&payload[subscription][product][public_signup_pages][url]=https%3A%2F%2Fgeneral-goods.chargify.com%2Fsubscribe%2Fkqvmfrbgd89q%2Fbasic&payload[subscription][product][public_signup_pages][id]=281240&payload[subscription][product][public_signup_pages][return_url]=&payload[subscription][product][public_signup_pages][return_params]=&payload[subscription][product][public_signup_pages][url]=https%3A%2F%2Fgeneral-goods.chargify.com%2Fsubscribe%2Fdkffht5dxfd8%2Fbasic&payload[subscription][product][public_signup_pages][id]=282694&payload[subscription][product][public_signup_pages][return_url]=&payload[subscription][product][public_signup_pages][return_params]=&payload[subscription][product][public_signup_pages][url]=https%3A%2F%2Fgeneral-goods.chargify.com%2Fsubscribe%2Fjwffwgdd95s8%2Fbasic&payload[subscription][credit_card][id]=10102821&payload[subscription][credit_card][first_name]=Pookie&payload[subscription][credit_card][last_name]=Test&payload[subscription][credit_card][masked_card_number]=XXXX-XXXX-XXXX-1&payload[subscription][credit_card][card_type]=bogus&payload[subscription][credit_card][expiration_month]=10&payload[subscription][credit_card][expiration_year]=2020&payload[subscription][credit_card][customer_id]=14585695&payload[subscription][credit_card][current_vault]=bogus&payload[subscription][credit_card][vault_token]=1&payload[subscription][credit_card][billing_address]=&payload[subscription][credit_card][billing_city]=&payload[subscription][credit_card][billing_state]=&payload[subscription][credit_card][billing_zip]=&payload[subscription][credit_card][billing_country]=&payload[subscription][credit_card][customer_vault_token]=&payload[subscription][credit_card][billing_address_2]=&payload[subscription][credit_card][payment_type]=credit_card&payload[subscription][credit_card][site_gateway_setting_id]=&payload[subscription][credit_card][gateway_handle]=&payload[transaction][id]=161537369&payload[transaction][subscription_id]=15100141&payload[transaction][type]=Payment&payload[transaction][kind]=&payload[transaction][transaction_type]=payment&payload[transaction][success]=true&payload[transaction][amount_in_cents]=6400&payload[transaction][memo]=Pookie%20Test%20-%20%2410%20Basic%20Plan%3A%20Renewal%20payment&payload[transaction][created_at]=2016-11-08%2016%3A22%3A20%20-0500&payload[transaction][starting_balance_in_cents]=6400&payload[transaction][ending_balance_in_cents]=0&payload[transaction][gateway_used]=bogus&payload[transaction][gateway_transaction_id]=53433&payload[transaction][gateway_response_code]=&payload[transaction][gateway_order_id]=&payload[transaction][payment_id]=&payload[transaction][product_id]=3792003&payload[transaction][tax_id]=&payload[transaction][component_id]=&payload[transaction][statement_id]=80168049&payload[transaction][customer_id]=14585695&payload[transaction][card_number]=XXXX-XXXX-XXXX-1&payload[transaction][card_expiration]=10%2F2020&payload[transaction][card_type]=bogus&payload[transaction][refunded_amount_in_cents]=0&payload[transaction][invoice_id]=&payload[event_id]=347299364", - "signature": "fbcf2f6be579f9658cff90c4373e0ca2", - "signature_hmac_sha_256": "db96654f5456c5460062feb944ac8bb1418f9d181ae04a8ed982fe9ffdca8de1" - } - } - ] - } - } - } - } - } - }, - "operationId": "listWebhooks", - "description": "## Webhooks Intro\n\nThe Webhooks API allows you to view a list of all webhooks and to selectively resend individual or groups of webhooks. Webhooks will be sent on endpoints specified by you. Endpoints can be added via API or Web UI. There is also an option to enable / disable webhooks via API request.\n\nWe recommend that you review Chargify's webhook documentation located in our help site. The following resources will help guide you on how to use webhooks in Chargify, in addition to these webhook endpoints:\n\n+ [Adding/editing new webhooks](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404448450317#configure-webhook-url)\n+ [Webhooks introduction and delivery information](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405568068365#webhooks-introduction-0-0)\n+ [Main webhook overview](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405357509645-Webhooks-Reference#webhooks-reference-0-0)\n+ [Available webhooks and payloads](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405357509645-Webhooks-Reference#events)\n\n## List Webhooks for a Site\n\nThis method allows you to fetch data about webhooks. You can pass query parameters if you want to filter webhooks.", - "parameters": [ - { - "$ref": "../components/parameters/webhook-status.yaml" - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "since_date", - "description": "Format YYYY-MM-DD. Returns Webhooks with the created_at date greater than or equal to the one specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "until_date", - "description": "Format YYYY-MM-DD. Returns Webhooks with the created_at date less than or equal to the one specified." - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "$ref": "../components/parameters/webhook-order.yaml" - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "subscription", - "description": "The Chargify id of a subscription you'd like to filter for" - } - ], - "x-operation-settings": { - "collectParameters": true - } - } - }, - "/webhooks/settings.json": { - "put": { - "summary": "Enable Webhooks", - "tags": [ - "Webhooks" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Enable-Webhooks-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "webhooks_enabled": true - } - } - } - } - } - } - }, - "operationId": "enableWebhooks", - "description": "This method allows you to enable webhooks via API for your site", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Enable-Webhooks-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "webhooks_enabled": true - } - } - } - } - } - } - } - }, - "/webhooks/replay.json": { - "post": { - "summary": "Replay Webhooks", - "tags": [ - "Webhooks" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Replay-Webhooks-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "status": "ok" - } - } - } - } - } - } - }, - "operationId": "replayWebhooks", - "description": "Posting to the replay endpoint does not immediately resend the webhooks. They are added to a queue and will be sent as soon as possible, depending on available system resources.\n\nYou may submit an array of up to 1000 webhook IDs to replay in the request.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Replay-Webhooks-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "ids": [ - 123456789, - 123456788 - ] - } - } - } - } - } - } - } - }, - "/endpoints.json": { - "post": { - "summary": "Create Endpoint", - "tags": [ - "Webhooks" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Endpoint-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "endpoint": { - "id": 1, - "url": "https://your.site/webhooks", - "site_id": 1, - "status": "enabled", - "webhook_subscriptions": [ - "payment_success", - "payment_failure" - ] - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "URL: invalid, only http and https supported" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createEndpoint", - "description": "The Chargify API allows you to create an endpoint and assign a list of webhooks subscriptions (events) to it.\n\nYou can check available events here.\n[Event keys](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405357509645-Webhooks-Reference#example-payloads)", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-or-Update-Endpoint-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "endpoint": { - "url": "https://your.site/webhooks", - "webhook_subscriptions": [ - "payment_success", - "payment_failure" - ] - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Endpoints", - "tags": [ - "Webhooks" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Endpoint.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "id": 11, - "url": "https://foobar.com/webhooks", - "site_id": 1, - "status": "enabled", - "webhook_subscriptions": [ - "payment_success", - "payment_failure" - ] - }, - { - "id": 12, - "url": "https:/example.com/webhooks", - "site_id": 1, - "status": "enabled", - "webhook_subscriptions": [ - "payment_success", - "payment_failure", - "refund_failure" - ] - } - ] - } - } - } - } - } - }, - "operationId": "listEndpoints", - "description": "This method returns created endpoints for site." - } - }, - "/endpoints/{endpoint_id}.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "endpoint_id", - "in": "path", - "required": true, - "description": "The Chargify id for the endpoint that should be updated" - } - ], - "put": { - "summary": "Update Endpoint", - "tags": [ - "Webhooks" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Endpoint-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Event key is not valid - foobar" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updateEndpoint", - "description": "You can update an Endpoint via the API with a PUT request to the resource endpoint.\n\nYou can change the `url` of your endpoint which consumes webhooks or list of `webhook_subscriptions`.\nCheck available [Event keys](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404448450317-Webhooks#configure-webhook-url).\n\nAlways send a complete list of events which you want subscribe/watch.\nSending an PUT request for existing endpoint with empty list of `webhook_subscriptions` will end with unsubscribe from all events.\n\nIf you want unsubscribe from specific event, just send a list of `webhook_subscriptions` without the specific event key.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-or-Update-Endpoint-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "endpoint": { - "url": "https://yout.site/webhooks/1/json.", - "webhook_subscriptions": [ - "payment_failure", - "payment_success", - "refund_failure" - ] - } - } - } - } - } - } - } - } - }, - "/site.json": { - "get": { - "summary": "Read Site", - "tags": [ - "Sites" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Site-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "site": { - "id": 0, - "name": "string", - "subdomain": "string", - "currency": "string", - "seller_id": 0, - "non_primary_currencies": [ - "string" - ], - "relationship_invoicing_enabled": true, - "customer_hierarchy_enabled": true, - "whopays_enabled": true, - "whopays_default_payer": "string", - "default_payment_collection_method": "string", - "organization_address": { - "street": null, - "line2": null, - "city": null, - "state": null, - "zip": null, - "country": null, - "name": "string", - "phone": "string" - }, - "tax_configuration": { - "kind": "custom", - "fully_configured": true, - "destination_address": "shipping_then_billing" - }, - "net_terms": { - "default_net_terms": 0, - "automatic_net_terms": 0, - "remittance_net_terms": 0, - "net_terms_on_remittance_signups_enabled": false, - "custom_net_terms_enabled": false - }, - "test": true, - "allocation_settings": { - "upgrade_charge": "prorated", - "downgrade_credit": "none", - "accrue_charge": "true" - } - } - } - } - } - } - } - } - }, - "operationId": "readSite", - "description": "This endpoint allows you to fetch some site data.\n\nFull documentation on Sites in the Chargify UI can be located [here](https://chargify.zendesk.com/hc/en-us/articles/4407870738587).\n\nSpecifically, the [Clearing Site Data](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405428327309) section is extremely relevant to this endpoint documentation.\n\n#### Relationship invoicing enabled\nIf site has RI enabled then you will see more settings like:\n\n \"customer_hierarchy_enabled\": true,\n \"whopays_enabled\": true,\n \"whopays_default_payer\": \"self\"\nYou can read more about these settings here:\n [Who Pays & Customer Hierarchy](https://chargify.zendesk.com/hc/en-us/articles/4407746683291)" - } - }, - "/sites/clear_data.json": { - "post": { - "summary": "Clear Site Data", - "tags": [ - "Sites" - ], - "operationId": "clearSite", - "description": "This call is asynchronous and there may be a delay before the site data is fully deleted. If you are clearing site data for an automated test, you will need to build in a delay and/or check that there are no products, etc., in the site before proceeding.\n\n**This functionality will only work on sites in TEST mode. Attempts to perform this on sites in “live” mode will result in a response of 403 FORBIDDEN.**\n", - "parameters": [ - { - "$ref": "../components/parameters/cleanup-scope.yaml" - } - ], - "responses": { - "200": { - "description": "OK" - } - } - } - }, - "/subscriptions/{subscription_id}/notes.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Create Subscription Note", - "operationId": "createSubscriptionNote", - "tags": [ - "Subscription Notes" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Note-Response.yaml" - } - } - } - } - }, - "description": "Use the following method to create a note for a subscription.\n\n## How to Use Subscription Notes\n\nNotes allow you to record information about a particular Subscription in a free text format.\n\nIf you have structured data such as birth date, color, etc., consider using Metadata instead.\n\nFull documentation on how to use Notes in the Chargify UI can be located [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404434903181-Subscription-Summary#notes).", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Subscription-Note-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "note": { - "body": "New test note.", - "sticky": true - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Subscription Notes", - "tags": [ - "Subscription Notes" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Subscription-Note-Response.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "note": { - "body": "Test note.", - "created_at": "2015-06-15T13:26:47-04:00", - "id": 5, - "sticky": false, - "subscription_id": 100046, - "updated_at": "2015-06-15T13:28:12-04:00" - } - }, - { - "note": { - "body": "Another test note.", - "created_at": "2015-06-15T12:04:46-04:00", - "id": 4, - "sticky": false, - "subscription_id": 100046, - "updated_at": "2015-06-15T13:26:33-04:00" - } - } - ] - } - } - } - } - } - }, - "operationId": "listSubscriptionNotes", - "description": "Use this method to retrieve a list of Notes associated with a Subscription. The response will be an array of Notes.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - } - ] - } - }, - "/subscriptions/{subscription_id}/notes/{note_id}.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - }, - { - "schema": { - "type": "integer" - }, - "name": "note_id", - "in": "path", - "required": true, - "description": "The Chargify id of the note" - } - ], - "get": { - "summary": "Read Subscription Note", - "tags": [ - "Subscription Notes" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Note-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "note": { - "body": "Test note.", - "created_at": "2015-06-15T13:26:47-04:00", - "id": 5, - "sticky": false, - "subscription_id": 100046, - "updated_at": "2015-06-15T13:28:12-04:00" - } - } - } - } - } - } - } - }, - "operationId": "readSubscriptionNote", - "description": "Once you have obtained the ID of the note you wish to read, use this method to show a particular note attached to a subscription." - }, - "put": { - "summary": "Update Subscription Note", - "tags": [ - "Subscription Notes" - ], - "operationId": "updateSubscriptionNote", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Note-Response.yaml" - } - } - } - } - }, - "description": "Use the following method to update a note for a Subscription.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Subscription-Note-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "note": { - "body": "Modified test note.", - "sticky": true - } - } - } - } - } - } - } - }, - "delete": { - "summary": "Delete Subscription Note", - "operationId": "deleteSubscriptionNote", - "tags": [ - "Subscription Notes" - ], - "responses": { - "200": { - "description": "OK" - } - }, - "description": "Use the following method to delete a note for a Subscription." - } - }, - "/customers.json": { - "post": { - "summary": "Create Customer", - "tags": [ - "Customers" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Customer-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "customer": { - "first_name": "Cathryn", - "last_name": "Parisian", - "email": "Stella.McLaughlin6@example.net", - "cc_emails": null, - "organization": "Greenholt - Oberbrunner", - "reference": null, - "id": 76, - "created_at": "2021-03-29T07:47:00-04:00", - "updated_at": "2021-03-29T07:47:00-04:00", - "address": "739 Stephon Bypass", - "address_2": "Apt. 386", - "city": "Sedrickchester", - "state": "KY", - "state_name": "Kentucky", - "zip": "46979-7719", - "country": "US", - "country_name": "United States", - "phone": "230-934-3685", - "verified": false, - "portal_customer_created_at": null, - "portal_invite_last_sent_at": null, - "portal_invite_last_accepted_at": null, - "tax_exempt": false, - "vat_number": null, - "parent_id": null, - "locale": "en-US" - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Customer-Error-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "errors": { - "customer": "can't be blank" - } - } - }, - "Example-2": { - "value": { - "errors": [ - "First name: cannot be blank.", - "Last name: cannot be blank.", - "Email address: cannot be blank." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createCustomer", - "description": "You may create a new Customer at any time, or you may create a Customer at the same time you create a Subscription. The only validation restriction is that you may only create one customer for a given reference value.\n\nIf provided, the `reference` value must be unique. It represents a unique identifier for the customer from your own app, i.e. the customer’s ID. This allows you to retrieve a given customer via a piece of shared information. Alternatively, you may choose to leave `reference` blank, and store Chargify’s unique ID for the customer, which is in the `id` attribute.\n\nFull documentation on how to locate, create and edit Customers in the Chargify UI can be located [here](https://chargify.zendesk.com/hc/en-us/articles/4407659914267).\n\n## Required Country Format\n\nChargify requires that you use the ISO Standard Country codes when formatting country attribute of the customer.\n\nCountries should be formatted as 2 characters. For more information, please see the following wikipedia article on [ISO_3166-1.](http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes)\n\n## Required State Format\n\nChargify requires that you use the ISO Standard State codes when formatting state attribute of the customer.\n\n+ US States (2 characters): [ISO_3166-2](https://en.wikipedia.org/wiki/ISO_3166-2:US)\n\n+ States Outside the US (2-3 characters): To find the correct state codes outside of the US, please go to [ISO_3166-1](http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes) and click on the link in the “ISO 3166-2 codes” column next to country you wish to populate.\n\n## Locale\n\nChargify allows you to attribute a language/region to your customer to deliver invoices in any required language.\nFor more: [Customer Locale](https://chargify.zendesk.com/hc/en-us/articles/4407870384283#customer-locale)", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Customer-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "customer": { - "first_name": "Martha", - "last_name": "Washington", - "email": "martha@example.com", - "cc_emails": "george@example.com", - "organization": "ABC, Inc.", - "reference": "1234567890", - "address": "123 Main Street", - "address_2": "Unit 10", - "city": "Anytown", - "state": "MA", - "zip": "02120", - "country": "US", - "phone": "555-555-1212", - "locale": "es-MX" - } - } - } - } - } - } - } - }, - "get": { - "summary": "List or Find Customers", - "tags": [ - "Customers" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Customer-Response.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "customer": { - "first_name": "Kayla", - "last_name": "Test", - "email": "kayla@example.com", - "cc_emails": "john@example.com, sue@example.com", - "organization": "", - "reference": null, - "id": 14126091, - "created_at": "2016-10-04T15:22:27-04:00", - "updated_at": "2016-10-04T15:22:30-04:00", - "address": "", - "address_2": "", - "city": "", - "state": "", - "zip": "", - "country": "", - "phone": "", - "verified": null, - "portal_customer_created_at": "2016-10-04T15:22:29-04:00", - "portal_invite_last_sent_at": "2016-10-04T15:22:30-04:00", - "portal_invite_last_accepted_at": null, - "tax_exempt": false - } - }, - { - "customer": { - "first_name": "Nick ", - "last_name": "Test", - "email": "nick@example.com", - "cc_emails": "john@example.com, sue@example.com", - "organization": "", - "reference": null, - "id": 14254093, - "created_at": "2016-10-13T16:52:51-04:00", - "updated_at": "2016-10-13T16:52:54-04:00", - "address": "", - "address_2": "", - "city": "", - "state": "", - "zip": "", - "country": "", - "phone": "", - "verified": null, - "portal_customer_created_at": "2016-10-13T16:52:54-04:00", - "portal_invite_last_sent_at": "2016-10-13T16:52:54-04:00", - "portal_invite_last_accepted_at": null, - "tax_exempt": false, - "parent_id": 123 - } - }, - { - "customer": { - "first_name": "Don", - "last_name": "Test", - "email": "don@example.com", - "cc_emails": "john@example.com, sue@example.com", - "organization": "", - "reference": null, - "id": 14332342, - "created_at": "2016-10-19T10:49:13-04:00", - "updated_at": "2016-10-19T10:49:19-04:00", - "address": "1737 15th St", - "address_2": "", - "city": "Boulder", - "state": "CO", - "zip": "80302", - "country": "US", - "phone": "", - "verified": null, - "portal_customer_created_at": "2016-10-19T10:49:19-04:00", - "portal_invite_last_sent_at": "2016-10-19T10:49:19-04:00", - "portal_invite_last_accepted_at": null, - "tax_exempt": false, - "parent_id": null - } - } - ] - } - } - } - } - } - }, - "operationId": "listCustomers", - "description": "This request will by default list all customers associated with your Site.\n\n## Find Customer\n\nUse the search feature with the `q` query parameter to retrieve an array of customers that matches the search query.\n\nCommon use cases are:\n\n+ Search by an email\n+ Search by a Chargify ID\n+ Search by an organization\n+ Search by a reference value from your application\n+ Search by a first or last name\n\nTo retrieve a single, exact match by reference, please use the [lookup endpoint](https://developers.chargify.com/docs/api-docs/b710d8fbef104-read-customer-by-reference).", - "parameters": [ - { - "schema": { - "$ref": "../components/schemas/Sort-Direction.yaml" - }, - "in": "query", - "name": "direction", - "description": "Direction to sort customers by time of creation" - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page-default-50.yaml" - }, - { - "$ref": "../components/parameters/basic-date-field.yaml" - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified.", - "name": "start_date" - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_date", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_datetime", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date.", - "name": "end_datetime" - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "q", - "description": "A search query by which to filter customers (can be an email, an ID, a reference, organization)" - } - ], - "x-operation-settings": { - "collectParameters": true - } - } - }, - "/customers/{id}.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "id", - "in": "path", - "required": true, - "description": "The Chargify id of the customer" - } - ], - "get": { - "summary": "Read Customer", - "tags": [ - "Customers" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Customer-Response.yaml" - } - } - } - } - }, - "operationId": "readCustomer", - "description": "This method allows to retrieve the Customer properties by Chargify-generated Customer ID.", - "parameters": [] - }, - "put": { - "summary": "Update Customer", - "tags": [ - "Customers" - ], - "operationId": "updateCustomer", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Customer-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "customer": { - "first_name": "Martha", - "last_name": "Washington", - "email": "martha.washington@example.com", - "cc_emails": "george.washington@example.com", - "organization": null, - "reference": null, - "id": 14967442, - "created_at": "2016-12-05T10:33:07-05:00", - "updated_at": "2016-12-05T10:38:00-05:00", - "address": null, - "address_2": null, - "city": null, - "state": null, - "zip": null, - "country": null, - "phone": null, - "verified": false, - "portal_customer_created_at": null, - "portal_invite_last_sent_at": null, - "portal_invite_last_accepted_at": null, - "tax_exempt": false, - "vat_number": "012345678" - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Customer-Error-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "errors": { - "customer": "can't be blank" - } - } - }, - "Example-2": { - "value": { - "errors": [ - "First name: cannot be blank.", - "Last name: cannot be blank.", - "Email address: cannot be blank." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "description": "This method allows to update the Customer.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Customer-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "customer": { - "first_name": "Martha", - "last_name": "Washington", - "email": "martha.washington@example.com" - } - } - } - } - } - } - } - }, - "delete": { - "summary": "Delete Customer", - "tags": [ - "Customers" - ], - "operationId": "deleteCustomer", - "responses": { - "204": { - "description": "No Content" - } - }, - "description": "This method allows you to delete the Customer." - } - }, - "/customers/lookup.json": { - "get": { - "summary": "Read Customer by Reference", - "tags": [ - "Customers" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Customer-Response.yaml" - } - } - } - } - }, - "operationId": "readCustomerByReference", - "description": "Use this method to return the customer object if you have the unique **Reference ID (Your App)** value handy. It will return a single match.", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "reference", - "required": true, - "description": "Customer reference" - } - ], - "x-internal": false - } - }, - "/customers/{customer_id}/subscriptions.json": { - "parameters": [ - { - "$ref": "../components/parameters/customer-id-path.yaml" - } - ], - "get": { - "summary": "List Customer Subscriptions", - "tags": [ - "Customers" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Subscription-Response.yaml" - } - } - } - } - } - }, - "operationId": "listCustomerSubscriptions", - "description": "This method lists all subscriptions that belong to a customer." - } - }, - "/portal/customers/{customer_id}/enable.json": { - "parameters": [ - { - "$ref": "../components/parameters/customer-id-path.yaml" - } - ], - "post": { - "summary": "Enable Billing Portal for Customer", - "tags": [ - "Billing Portal" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Customer-Response.yaml" - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Portal is already enabled for this customer." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "enableBillingPortalForCustomer", - "description": "## Billing Portal Documentation\n\nFull documentation on how the Billing Portal operates within the Chargify UI can be located [here](https://chargify.zendesk.com/hc/en-us/articles/4407648972443).\n\nThis documentation is focused on how the to configure the Billing Portal Settings, as well as Subscriber Interaction and Merchant Management of the Billing Portal.\n\nYou can use this endpoint to enable Billing Portal access for a Customer, with the option of sending the Customer an Invitation email at the same time.\n\n## Billing Portal Security\n\nIf your customer has been invited to the Billing Portal, then they will receive a link to manage their subscription (the “Management URL”) automatically at the bottom of their statements, invoices, and receipts. **This link changes periodically for security and is only valid for 65 days.**\n\nIf you need to provide your customer their Management URL through other means, you can retrieve it via the API. Because the URL is cryptographically signed with a timestamp, it is not possible for merchants to generate the URL without requesting it from Chargify.\n\nIn order to prevent abuse & overuse, we ask that you request a new URL only when absolutely necessary. Management URLs are good for 65 days, so you should re-use a previously generated one as much as possible. If you use the URL frequently (such as to display on your website), please **do not** make an API request to Chargify every time.", - "parameters": [ - { - "schema": { - "$ref": "../components/schemas/Auto-Invite.yaml" - }, - "in": "query", - "name": "auto_invite", - "description": "When set to 1, an Invitation email will be sent to the Customer.\nWhen set to 0, or not sent, an email will not be sent.\nUse in query: `auto_invite=1`." - } - ] - } - }, - "/portal/customers/{customer_id}/management_link.json": { - "parameters": [ - { - "$ref": "../components/parameters/customer-id-path.yaml" - } - ], - "get": { - "summary": "Read Billing Portal Management Link", - "tags": [ - "Billing Portal" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Portal-Management-Link.yaml" - }, - "examples": { - "Example": { - "value": { - "url": "https://www.billingportal.com/manage/19804639/1517596469/bd16498719a7d3e6", - "fetch_count": 1, - "created_at": "2018-02-02T18:34:29Z", - "new_link_available_at": "2018-02-17T18:34:29Z", - "expires_at": "2018-04-08T17:34:29Z", - "last_invite_sent_at": "2018-02-02T18:34:29Z" - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Billing Portal is not enabled for this customer." - ] - } - } - } - } - } - }, - "429": { - "description": "Too Many Requests", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Too-Many-Management-Link-Requests-Error.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": { - "error": "Too many requests for this customer's management link", - "new_link_available_at": "2023-10-20T10:46:56Z" - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.", - "429": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "readBillingPortalLink", - "description": "This method will provide to the API user the exact URL required for a subscriber to access the Billing Portal.\n\n## Rules for Management Link API\n\n+ When retrieving a management URL, multiple requests for the same customer in a short period will return the **same** URL\n+ We will not generate a new URL for 15 days\n+ You must cache and remember this URL if you are going to need it again within 15 days\n+ Only request a new URL after the `new_link_available_at` date\n+ You are limited to 15 requests for the same URL. If you make more than 15 requests before `new_link_available_at`, you will be blocked from further Management URL requests (with a response code `429`)" - } - }, - "/portal/customers/{customer_id}/invitations/invite.json": { - "parameters": [ - { - "$ref": "../components/parameters/customer-id-path.yaml" - } - ], - "post": { - "summary": "Resend Billing Portal Invitation", - "tags": [ - "Billing Portal" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Resent-Invitation.yaml" - }, - "examples": { - "Example": { - "value": { - "last_sent_at": "enim Duis esse dolore", - "last_accepted_at": "adipisicing magna do in irure", - "send_invite_link_text": "veniam sit", - "uninvited_count": 66254678 - } - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Too many requests for this customer. You can perform 5 requests within 00:30:00." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "resendBillingPortalInvitation", - "description": "You can resend a customer's Billing Portal invitation.\n\nIf you attempt to resend an invitation 5 times within 30 minutes, you will receive a `422` response with `error` message in the body.\n\nIf you attempt to resend an invitation when the Billing Portal is already disabled for a Customer, you will receive a `422` error response.\n\nIf you attempt to resend an invitation when the Billing Portal is already disabled for a Customer, you will receive a `422` error response.\n\nIf you attempt to resend an invitation when the Customer does not exist a Customer, you will receive a `404` error response.\n\n## Limitations\n\nThis endpoint will only return a JSON response." - } - }, - "/portal/customers/{customer_id}/invitations/revoke.json": { - "parameters": [ - { - "$ref": "../components/parameters/customer-id-path.yaml" - } - ], - "delete": { - "summary": "Revoke Billing Portal Invitation for Customer", - "tags": [ - "Billing Portal" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Revoked-Invitation.yaml" - }, - "examples": { - "Example": { - "value": { - "last_sent_at": "Not Invited", - "last_accepted_at": "Invite Revoked", - "uninvited_count": 8 - } - } - } - } - } - } - }, - "operationId": "revokeBillingPortalAccess", - "description": "You can revoke a customer's Billing Portal invitation.\n\nIf you attempt to revoke an invitation when the Billing Portal is already disabled for a Customer, you will receive a 422 error response.\n\n## Limitations\n\nThis endpoint will only return a JSON response." - } - }, - "/stats.json": { - "get": { - "summary": "Read Site Stats", - "tags": [ - "Insights" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Site-Summary.yaml" - }, - "examples": { - "Example": { - "value": { - "seller_name": "Acme, Inc.", - "site_name": "Production", - "site_id": 12345, - "site_currency": "USD", - "stats": { - "total_subscriptions": 120, - "subscriptions_today": 4, - "total_revenue": "$45,978.81", - "revenue_today": "$1,405.12", - "revenue_this_month": "$10,000.00", - "revenue_this_year": "$27,935.24" - } - } - } - } - } - } - } - }, - "operationId": "readSiteStats", - "description": "The Stats API is a very basic view of some Site-level stats. This API call only answers with JSON responses. An XML version is not provided.\n\n## Stats Documentation\n\nThere currently is not a complimentary matching set of documentation that compliments this endpoint. However, each Site's dashboard will reflect the summary of information provided in the Stats reposnse.\n\n```\nhttps://subdomain.chargify.com/dashboard\n```" - } - }, - "/referral_codes/validate.json": { - "get": { - "summary": "Validate Referral Code", - "tags": [ - "Referral Codes" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Referral-Validation-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "referral_code": { - "id": 1032514, - "site_id": 31615, - "subscription_id": 16254270, - "code": "9b6cdw" - } - } - } - } - } - } - }, - "404": { - "description": "Not Found", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Single-String-Error-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": "Referral code is invalid." - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Invalid referral code." - } - }, - "operationId": "validateReferralCode", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "required": true, - "name": "code", - "description": "The referral code you are trying to validate" - } - ], - "description": "Use this method to determine if the referral code is valid and applicable within your Site. This method is useful for validating referral codes that are entered by a customer.\n\n## Referrals Documentation\n\nFull documentation on how to use the referrals feature in the Chargify UI can be located [here](https://chargify.zendesk.com/hc/en-us/articles/4407802831643).\n\n## Server Response\n\nIf the referral code is valid the status code will be `200` and the referral code will be returned. If the referral code is invalid, a `404` response will be returned." - } - }, - "/reason_codes.json": { - "post": { - "summary": "Create Reason Code", - "tags": [ - "Reason Codes" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Reason-Code-Response.yaml" - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Code: cannot be blank.", - "Code: This code is already in use.", - "Description: cannot be blank." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createReasonCode", - "description": "# Reason Codes Intro\n\nReasonCodes are a way to gain a high level view of why your customers are cancelling the subcription to your product or service.\n\nAdd a set of churn reason codes to be displayed in-app and/or the Chargify Billing Portal. As your subscribers decide to cancel their subscription, learn why they decided to cancel.\n\n## Reason Code Documentation\n\nFull documentation on how Reason Codes operate within Chargify can be located under the following links.\n\n[Churn Reason Codes](https://chargify.zendesk.com/hc/en-us/articles/4407896775579#churn-reason-codes)\n\n## Create Reason Code\n\nThis method gives a merchant the option to create a reason codes for a given Site.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Reason-Code-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "reason_code": { - "code": "NOTHANKYOU", - "description": "No thank you!", - "position": 5 - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Reason Codes", - "tags": [ - "Reason Codes" - ], - "operationId": "listReasonCodes", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Reason-Code-Response.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "reason_code": { - "id": 2, - "site_id": 2, - "code": "LARGE", - "description": "This is too complicated", - "position": 1, - "created_at": "2017-02-16T16:49:07-05:00", - "updated_at": "2017-02-17T16:29:51-05:00" - } - }, - { - "reason_code": { - "id": 1, - "site_id": 2, - "code": "CH1", - "description": "This doesnt meet my needs", - "position": 2, - "created_at": "2017-02-16T16:48:45-05:00", - "updated_at": "2017-02-17T16:29:59-05:00" - } - }, - { - "reason_code": { - "id": 5, - "site_id": 2, - "code": "HAN99", - "description": "Hard to setup", - "position": 3, - "created_at": "2017-02-17T16:29:42-05:00", - "updated_at": "2017-02-17T16:29:59-05:00" - } - } - ] - } - } - } - } - } - }, - "description": "This method gives a merchant the option to retrieve a list of all of the current churn codes for a given site.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - } - ] - } - }, - "/reason_codes/{reason_code_id}.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "reason_code_id", - "in": "path", - "required": true, - "description": "The Chargify id of the reason code" - } - ], - "get": { - "summary": "Read Reason Code", - "tags": [ - "Reason Codes" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Reason-Code-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "readReasonCode", - "description": "This method gives a merchant the option to retrieve a list of a particular code for a given Site by providing the unique numerical ID of the code." - }, - "put": { - "summary": "Update Reason Code", - "tags": [ - "Reason Codes" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Reason-Code-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "updateReasonCode", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Reason-Code-Request.yaml" - } - } - } - }, - "description": "This method gives a merchant the option to update an existing reason code for a given site." - }, - "delete": { - "summary": "Delete Reason Code", - "tags": [ - "Reason Codes" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Ok-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "ok": "ok" - } - } - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "deleteReasonCode", - "description": "This method gives a merchant the option to delete one reason code from the Churn Reason Codes. This code will be immediately removed. This action is not reversable." - } - }, - "/{resource_type}/metafields.json": { - "parameters": [ - { - "$ref": "../components/parameters/resource-type.yaml" - } - ], - "post": { - "summary": "Create Metafields", - "tags": [ - "Custom Fields" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Metafield.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "name": "Color", - "scope": { - "hosted": [], - "csv": "0", - "statements": "0", - "invoices": "0", - "portal": "0" - }, - "data_count": 0, - "input_type": "text", - "enum": null - }, - { - "name": "Brand", - "scope": { - "hosted": [], - "csv": "0", - "statements": "0", - "invoices": "0", - "portal": "0" - }, - "data_count": 0, - "input_type": "text", - "enum": null - } - ] - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Single-Error-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "error": "'name' must be present to create or update metafields" - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createMetafields", - "description": "## Custom Fields: Metafield Intro\n\n**Chargify refers to Custom Fields in the API documentation as metafields and metadata.** Within the Chargify UI, metadata and metafields are grouped together under the umbrella of \"Custom Fields.\" All of our UI-based documentation that references custom fields will not cite the terminology metafields or metadata.\n\n+ **Metafield is the custom field**\n+ **Metadata is the data populating the custom field.**\n\nChargify Metafields are used to add meaningful attributes to subscription and customer resources. Full documentation on how to create Custom Fields in the Chargify UI can be located [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405332553613-Custom-Fields-Reference). For additional documentation on how to record data within custom fields, please see our subscription-based documentation [here.](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404434903181-Subscription-Summary#custom-fields)\n\nMetafield are the place where you will set up your resource to accept additional data. It is scoped to the site instead of a specific customer or subscription. Think of it as the key, and Metadata as the value on every record.\n\n## Create Metafields\n\nUse this endpoint to create metafields for your Site. Metafields can be populated with metadata after the fact.\n\nEach site is limited to 100 unique Metafields (i.e. keys, or names) per resource. This means you can have 100 Metafields for Subscription and another 100 for Customer.\n\n### Metafields \"On-the-Fly\"\n\nIt is possible to create Metafields “on the fly” when you create your Metadata – if a non-existant name is passed when creating Metadata, a Metafield for that key will be automatically created. The Metafield API, however, gives you more control over your “keys”.\n\n### Metafield Scope Warning\n\nIf configuring metafields in the Admin UI or via the API, be careful sending updates to metafields with the scope attribute – **if a partial update is sent it will overwrite the current configuration**.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Metafields-Request.yaml" - }, - "examples": { - "Single-Metafield": { - "value": { - "metafields": { - "name": "Dropdown field", - "input_type": "dropdown", - "enum": [ - "option 1", - "option 2" - ], - "scope": { - "public_edit": "1", - "public_show": "1" - } - } - } - }, - "Multiple-Metafields": { - "value": { - "metafields": [ - { - "name": "Color" - }, - { - "name": "Brand" - } - ] - } - } - } - } - } - }, - "parameters": [] - }, - "get": { - "summary": "List Metafields", - "tags": [ - "Custom Fields" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Metafields-Response.yaml" - }, - "examples": { - "example-1": { - "value": { - "total_count": 0, - "current_page": 0, - "total_pages": 0, - "per_page": 0, - "metafields": [ - { - "id": 0, - "name": "string", - "scope": { - "csv": "0", - "statements": "0", - "invoices": "0", - "portal": "0", - "public_show": "0", - "public_edit": "0" - }, - "data_count": 0, - "input_type": "text", - "enum": null - } - ] - } - } - } - } - } - } - }, - "operationId": "listMetafields", - "description": "This endpoint lists metafields associated with a site. The metafield description and usage is contained in the response.", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "name", - "description": "filter by the name of the metafield" - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "$ref": "../components/parameters/sort-direction.yaml" - } - ], - "x-operation-settings": { - "collectParameters": true - } - }, - "put": { - "summary": "Update Metafield", - "tags": [ - "Custom Fields" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Metafield.yaml" - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Single-Error-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "error": "Metafield name must be unique for the Attachment Type" - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updateMetafield", - "description": "Use the following method to update metafields for your Site. Metafields can be populated with metadata after the fact.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Metafields-Request.yaml" - } - } - } - } - }, - "delete": { - "tags": [ - "Custom Fields" - ], - "summary": "Delete Metafield", - "operationId": "deleteMetafield", - "responses": { - "200": { - "description": "OK" - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "description": "Use the following method to delete a metafield. This will remove the metafield from the Site.\n\nAdditionally, this will remove the metafield and associated metadata with all Subscriptions on the Site.", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "name", - "description": "The name of the metafield to be deleted" - } - ] - } - }, - "/{resource_type}/{resource_id}/metadata.json": { - "parameters": [ - { - "$ref": "../components/parameters/resource-type.yaml" - }, - { - "schema": { - "type": "integer" - }, - "name": "resource_id", - "in": "path", - "required": true, - "description": "The Chargify id of the customer or the subscription for which the metadata applies" - } - ], - "post": { - "summary": "Create Metadata", - "tags": [ - "Custom Fields" - ], - "operationId": "createMetadata", - "description": "## Custom Fields: Metadata Intro\n\n**Chargify refers to Custom Fields in the API documentation as metafields and metadata.** Within the Chargify UI, metadata and metafields are grouped together under the umbrella of \"Custom Fields.\" All of our UI-based documentation that references custom fields will not cite the terminology metafields or metadata.\n\n+ **Metafield is the custom field**\n+ **Metadata is the data populating the custom field.**\n\nChargify Metafields are used to add meaningful attributes to subscription and customer resources. Full documentation on how to create Custom Fields in the Chargify UI can be located [here](https://chargify.zendesk.com/hc/en-us/articles/4407659856411). For additional documentation on how to record data within custom fields, please see our subscription-based documentation [here.](https://chargify.zendesk.com/hc/en-us/articles/4407884887835#custom-fields)\n\nMetadata is associated to a customer or subscription, and corresponds to a Metafield. When creating a new metadata object for a given record, **if the metafield is not present it will be created**.\n\n## Metadata limits\n\nMetadata values are limited to 2kB in size. Additonally, there are limits on the number of unique metafields available per resource.\n\n## Create Metadata\n\nThis method will create a metafield for the site on the fly if it does not already exist, and populate the metadata value.\n\n### Subscription or Customer Resource\n\nPlease pay special attention to the resource you use when creating metadata.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Metadata-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "metadata": [ - { - "name": "Color", - "value": "Blue" - }, - { - "name": "Something", - "value": "Useful" - } - ] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Metadata.yaml" - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Single-Error-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "error": "'name' must be present to create or update metafields" - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - } - }, - "get": { - "summary": "List Metadata", - "tags": [ - "Custom Fields" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Paginated-Metadata.yaml" - } - } - } - } - }, - "operationId": "listMetadata", - "description": "This request will list all of the metadata belonging to a particular resource (ie. subscription, customer) that is specified.\n\n## Metadata Data\n\nThis endpoint will also display the current stats of your metadata to use as a tool for pagination.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - } - ] - }, - "put": { - "summary": "Update Metadata", - "tags": [ - "Custom Fields" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Metadata.yaml" - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Single-Error-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "error": "'name' must be present to create or update metafields" - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updateMetadata", - "description": "This method allows you to update the existing metadata associated with a subscription or customer.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Metadata-Request.yaml" - } - } - } - } - }, - "delete": { - "summary": "Delete Metadata", - "tags": [ - "Custom Fields" - ], - "responses": { - "200": { - "description": "OK" - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "deleteMetadata", - "description": "This method removes the metadata from the subscriber/customer cited.\n\n## Query String Usage\n\nFor instance if you wanted to delete the metadata for customer 99 named weight you would request:\n\n```\nhttps://acme.chargify.com/customers/99/metadata.json?name=weight\n```\n\nIf you want to delete multiple metadata fields for a customer 99 named: `weight` and `age` you wrould request:\n```\nhttps://acme.chargify.com/customers/99/metadata.json?names[]=weight&names[]=age\n```\n\n## Successful Response\n\nFor a success, there will be a code `200` and the plain text response `true`.\n\n## Unsuccessful Response\n\nWhen a failed response is encountered, you will receive a `404` response and the plain text response of `true`.", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "name", - "description": "Name of field to be removed." - }, - { - "schema": { - "type": "array", - "items": { - "type": "string" - } - }, - "in": "query", - "description": "Names of fields to be removed. Use in query: `names[]=field1&names[]=my-field&names[]=another-field`.", - "name": "names[]", - "style": "form", - "explode": true - } - ] - } - }, - "/{resource_type}/metadata.json": { - "parameters": [ - { - "$ref": "../components/parameters/resource-type.yaml" - } - ], - "get": { - "summary": "List Metadata for Resource Type", - "tags": [ - "Custom Fields" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Paginated-Metadata.yaml" - } - } - } - } - }, - "operationId": "listMetadataForResourceType", - "description": "This method will provide you information on usage of metadata across your selected resource (ie. subscriptions, customers)\n\n## Metadata Data\n\nThis endpoint will also display the current stats of your metadata to use as a tool for pagination.\n\n### Metadata for multiple records\n\n`https://acme.chargify.com/subscriptions/metadata.json?resource_ids[]=1&resource_ids[]=2`\n\n## Read Metadata for a Site\n\nThis endpoint will list the number of pages of metadata information that are contained within a site.", - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "$ref": "../components/schemas/Basic-Date-Field.yaml" - }, - "in": "query", - "name": "date_field", - "description": "The type of filter you would like to apply to your search." - }, - { - "schema": { - "type": "string", - "format": "date" - }, - "in": "query", - "name": "start_date", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns metadata with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string", - "format": "date" - }, - "in": "query", - "name": "end_date", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns metadata with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string", - "format": "date-time" - }, - "in": "query", - "name": "start_datetime", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns metadata with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date." - }, - { - "schema": { - "type": "string", - "format": "date-time" - }, - "in": "query", - "name": "end_datetime", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns metadata with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date." - }, - { - "schema": { - "type": "boolean" - }, - "in": "query", - "name": "with_deleted", - "description": "Allow to fetch deleted metadata." - }, - { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "maxItems": 50 - }, - "in": "query", - "name": "resource_ids[]", - "style": "form", - "explode": true, - "description": "Allow to fetch metadata for multiple records based on provided ids. Use in query: `resource_ids[]=122&resource_ids[]=123&resource_ids[]=124`." - }, - { - "$ref": "../components/parameters/sort-direction.yaml" - } - ], - "x-operation-settings": { - "collectParameters": true - } - } - }, - "/product_families/{product_family_id}/coupons.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "product_family_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product family to which the coupon belongs" - } - ], - "post": { - "summary": "Create Coupon", - "tags": [ - "Coupons" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Coupon-Response.yaml" - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Expiration Date cannot be in the past" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createCoupon", - "description": "## Coupons Documentation\n\nCoupons can be administered in the Chargify application or created via API. Please view our section on [creating coupons](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404742830733) for more information.\n\nAdditionally, for documentation on how to apply a coupon to a subscription within the Chargify UI, please see our documentation [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404761012877).\n\n## Create Coupon\n\nThis request will create a coupon, based on the provided information.\n\nWhen creating a coupon, you must specify a product family using the `product_family_id`. If no `product_family_id` is passed, the first product family available is used. You will also need to formulate your URL to cite the Product Family ID in your request.\n\nYou can restrict a coupon to only apply to specific products / components by optionally passing in hashes of `restricted_products` and/or `restricted_components` in the format:\n`{ \"\": boolean_value }`", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-or-Update-Coupon.yaml" - }, - "examples": { - "Percentage Coupon Example": { - "value": { - "coupon": { - "name": "15% off", - "code": "15OFF", - "description": "15% off for life", - "percentage": 15, - "allow_negative_balance": false, - "recurring": false, - "end_date": "2012-08-29T12:00:00-04:00", - "product_family_id": "2", - "stackable": true, - "compounding_strategy": "compound", - "exclude_mid_period_allocations": true, - "apply_on_cancel_at_end_of_period": true - }, - "restricted_products": { - "1": true - }, - "restricted_components": { - "1": true, - "2": false - } - } - }, - "Flat Amount Coupon Example": { - "value": { - "coupon": { - "name": "$10 off", - "code": "10OFF", - "description": "$10 off for life", - "amount_in_cents": 1000, - "allow_negative_balance": false, - "recurring": false, - "end_date": "2012-08-29T12:00:00-04:00", - "product_family_id": "2", - "stackable": true, - "compounding_strategy": "compound", - "exclude_mid_period_allocations": true, - "apply_on_cancel_at_end_of_period": true - }, - "restricted_products": { - "1": true - }, - "restricted_components": { - "1": true, - "2": false - } - } - } - } - } - }, - "description": "" - } - }, - "get": { - "summary": "List Coupons for Product Family", - "tags": [ - "Coupons" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Coupon-Response.yaml" - } - }, - "examples": { - "example": { - "value": [ - { - "coupon": { - "id": 999999, - "name": "50% coupon", - "code": "50PERCENT", - "description": "50 PERCENT OFF", - "amount_in_cents": null, - "product_family_id": 527890, - "created_at": "2016-10-21T17:02:08-04:00", - "updated_at": "2016-10-21T17:06:11-04:00", - "start_date": "2016-10-21T17:02:08-04:00", - "end_date": null, - "percentage": "50", - "recurring": true, - "duration_period_count": null, - "duration_interval": 1, - "duration_interval_unit": "day", - "allow_negative_balance": true, - "archived_at": null, - "conversion_limit": "100", - "stackable": false, - "compounding_strategy": "compound", - "coupon_restrictions": [], - "use_site_exchange_rate": true - } - }, - { - "coupon": { - "id": 123456, - "name": "100% coupon", - "code": "100PERCENT", - "description": "100 PERCENT OFF", - "amount_in_cents": null, - "product_family_id": 527890, - "created_at": "2016-10-21T17:02:08-04:00", - "updated_at": "2016-10-21T17:06:11-04:00", - "start_date": "2016-10-21T17:02:08-04:00", - "end_date": null, - "percentage": "50", - "recurring": true, - "duration_period_count": null, - "duration_interval": 1, - "duration_interval_unit": "day", - "allow_negative_balance": true, - "archived_at": null, - "conversion_limit": "100", - "stackable": false, - "compounding_strategy": "compound", - "coupon_restrictions": [], - "use_site_exchange_rate": true - } - }, - { - "coupon": { - "id": 888888, - "name": "25% coupon", - "code": "25PERCENT", - "description": "25 PERCENT OFF", - "amount_in_cents": null, - "product_family_id": 527890, - "created_at": "2016-10-21T17:02:08-04:00", - "updated_at": "2016-10-21T17:06:11-04:00", - "start_date": "2016-10-21T17:02:08-04:00", - "end_date": null, - "percentage": "25", - "recurring": true, - "duration_period_count": null, - "duration_interval": 1, - "duration_interval_unit": "day", - "allow_negative_balance": true, - "archived_at": null, - "conversion_limit": "100", - "stackable": false, - "compounding_strategy": "compound", - "coupon_restrictions": [ - { - "id": 37, - "item_type": "Component", - "item_id": 519, - "name": "test", - "handle": null - } - ], - "use_site_exchange_rate": true - } - } - ] - } - } - } - } - } - }, - "operationId": "listCouponsForProductFamily", - "description": "List coupons for a specific Product Family in a Site.\n\nIf the coupon is set to `use_site_exchange_rate: true`, it will return pricing based on the current exchange rate. If the flag is set to false, it will return all of the defined prices for each currency.", - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page-default-30.yaml" - }, - { - "schema": { - "$ref": "../components/schemas/Basic-Date-Field.yaml" - }, - "in": "query", - "name": "filter[date_field]", - "description": "The type of filter you would like to apply to your search. Use in query `filter[date_field]=created_at`." - }, - { - "schema": { - "type": "string", - "format": "date", - "example": "2011-12-15" - }, - "in": "query", - "name": "filter[end_date]", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns coupons with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. Use in query `filter[date_field]=2011-12-15`." - }, - { - "schema": { - "type": "string", - "format": "date-time", - "example": "2019-06-07T17:20:06Z" - }, - "in": "query", - "name": "filter[end_datetime]", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns coupons with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. Use in query `?filter[end_datetime]=2011-12-1T10:15:30+01:00`." - }, - { - "schema": { - "type": "string", - "format": "date", - "example": "2011-12-17" - }, - "in": "query", - "name": "filter[start_date]", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns coupons with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. Use in query `filter[start_date]=2011-12-17`." - }, - { - "schema": { - "type": "string", - "format": "date-time", - "example": "2011-12-19T10:15:30+01:00" - }, - "in": "query", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns coupons with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. Use in query `filter[start_datetime]=2011-12-19T10:15:30+01:00`.", - "name": "filter[start_datetime]" - }, - { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [ - 1, - 2, - 3 - ], - "minItems": 1 - }, - "in": "query", - "name": "filter[ids]", - "description": "Allows fetching coupons with matching id based on provided values. Use in query `filter[ids]=1,2,3`.", - "style": "form", - "explode": false - }, - { - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "free", - "free_trial" - ] - }, - "in": "query", - "name": "filter[codes]", - "description": "Allows fetching coupons with matching codes based on provided values. Use in query `filter[codes]=free,free_trial`.", - "style": "form", - "explode": false - }, - { - "schema": { - "type": "boolean", - "example": true - }, - "in": "query", - "name": "currency_prices", - "description": "When fetching coupons, if you have defined multiple currencies at the site level, you can optionally pass the `?currency_prices=true` query param to include an array of currency price data in the response. Use in query `currency_prices=true`." - }, - { - "schema": { - "type": "boolean", - "example": true - }, - "in": "query", - "description": "Allows fetching coupons with matching use_site_exchange_rate based on provided value. Use in query `filter[use_site_exchange_rate]=true`.", - "name": "filter[use_site_exchange_rate]" - } - ], - "x-operation-settings": { - "collectParameters": true - } - } - }, - "/coupons/find.json": { - "get": { - "summary": "Find Coupon", - "tags": [ - "Coupons" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Coupon-Response.yaml" - } - } - } - } - }, - "operationId": "findCoupon", - "description": "You can search for a coupon via the API with the find method. By passing a code parameter, the find will attempt to locate a coupon that matches that code. If no coupon is found, a 404 is returned.\n\nIf you have more than one product family and if the coupon you are trying to find does not belong to the default product family in your site, then you will need to specify (either in the url or as a query string param) the product family id.", - "parameters": [ - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "product_family_id", - "description": "The Chargify id of the product family to which the coupon belongs" - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "code", - "description": "The code of the coupon" - } - ] - } - }, - "/product_families/{product_family_id}/coupons/{coupon_id}.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "product_family_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product family to which the coupon belongs" - }, - { - "schema": { - "type": "integer" - }, - "name": "coupon_id", - "in": "path", - "required": true, - "description": "The Chargify id of the coupon" - } - ], - "get": { - "summary": "Read Coupon", - "tags": [ - "Coupons" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Coupon-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "coupon": { - "id": 67, - "name": "Foo Bar", - "code": "YEPPER99934", - "description": "my cool coupon", - "amount_in_cents": null, - "product_family_id": 4, - "product_family_name": "Billing Plans", - "created_at": "2017-11-08T10:01:15-05:00", - "updated_at": "2017-11-08T10:01:15-05:00", - "start_date": "2017-11-08T10:01:15-05:00", - "end_date": null, - "percentage": "33.3333", - "duration_period_count": null, - "duration_interval": null, - "duration_interval_unit": null, - "allow_negative_balance": false, - "archived_at": null, - "conversion_limit": null, - "stackable": true, - "compounding_strategy": "compound", - "coupon_restrictions": [] - } - } - } - } - } - } - } - }, - "operationId": "readCoupon", - "description": "You can retrieve the Coupon via the API with the Show method. You must identify the Coupon in this call by the ID parameter that Chargify assigns.\nIf instead you would like to find a Coupon using a Coupon code, see the Coupon Find method.\n\nWhen fetching a coupon, if you have defined multiple currencies at the site level, you can optionally pass the `?currency_prices=true` query param to include an array of currency price data in the response.\n\nIf the coupon is set to `use_site_exchange_rate: true`, it will return pricing based on the current exchange rate. If the flag is set to false, it will return all of the defined prices for each currency.", - "parameters": [] - }, - "put": { - "summary": "Update Coupon", - "tags": [ - "Coupons" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Coupon-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "coupon": { - "id": 67, - "name": "Foo Bar", - "code": "YEPPER99934", - "description": "my cool coupon", - "amount_in_cents": 10000, - "product_family_id": 4, - "created_at": "2017-11-08T10:01:15-05:00", - "updated_at": "2017-11-08T10:01:15-05:00", - "start_date": "2017-11-08T10:01:15-05:00", - "end_date": null, - "percentage": null, - "recurring": false, - "duration_period_count": null, - "duration_interval": null, - "duration_interval_unit": null, - "allow_negative_balance": false, - "archived_at": null, - "conversion_limit": null, - "stackable": true, - "compounding_strategy": "compound", - "coupon_restrictions": [] - } - } - } - } - } - } - } - }, - "operationId": "updateCoupon", - "description": "## Update Coupon\n\nYou can update a Coupon via the API with a PUT request to the resource endpoint.\n\nYou can restrict a coupon to only apply to specific products / components by optionally passing in hashes of `restricted_products` and/or `restricted_components` in the format:\n`{ \"\": boolean_value }`", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-or-Update-Coupon.yaml" - }, - "examples": { - "Example": { - "value": { - "coupon": { - "name": "15% off", - "code": "15OFF", - "description": "15% off for life", - "percentage": 15, - "allow_negative_balance": false, - "recurring": false, - "end_date": "2012-08-29T12:00:00-04:00", - "product_family_id": "2", - "stackable": true, - "compounding_strategy": "compound" - }, - "restricted_products": { - "1": true - }, - "restricted_components": { - "1": true, - "2": false - } - } - } - } - } - }, - "description": "" - } - }, - "delete": { - "summary": "Archive Coupon", - "tags": [ - "Coupons" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Coupon-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "coupon": { - "id": 67, - "name": "Foo Bar", - "code": "YEPPER99934", - "description": "my cool coupon", - "amount_in_cents": 10000, - "product_family_id": 4, - "created_at": "2017-11-08T10:01:15-05:00", - "updated_at": "2017-11-08T10:01:15-05:00", - "start_date": "2017-11-08T10:01:15-05:00", - "end_date": null, - "percentage": null, - "recurring": false, - "duration_period_count": null, - "duration_interval": null, - "duration_interval_unit": null, - "allow_negative_balance": false, - "archived_at": "2016-12-02T13:09:33-05:00", - "conversion_limit": null, - "stackable": true, - "compounding_strategy": "compound", - "coupon_restrictions": [] - } - } - } - } - } - } - } - }, - "operationId": "archiveCoupon", - "description": "You can archive a Coupon via the API with the archive method.\nArchiving makes that Coupon unavailable for future use, but allows it to remain attached and functional on existing Subscriptions that are using it.\nThe `archived_at` date and time will be assigned." - } - }, - "/coupons.json": { - "get": { - "summary": "List Coupons", - "tags": [ - "Coupons" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Coupon-Response.yaml" - } - }, - "examples": { - "example": { - "value": [ - { - "coupon": { - "id": 0, - "name": "string", - "code": "string", - "description": "string", - "amount": 0, - "amount_in_cents": 0, - "product_family_id": 0, - "product_family_name": "string", - "start_date": "2021-05-03T16:00:21-04:00", - "end_date": "2023-05-05T16:00:21-04:00", - "percentage": "10", - "recurring": true, - "recurring_scheme": "do_not_recur", - "duration_period_count": 0, - "duration_interval": 0, - "duration_interval_unit": "string", - "duration_interval_span": "string", - "allow_negative_balance": true, - "archived_at": null, - "conversion_limit": "string", - "stackable": true, - "compounding_strategy": "compound", - "use_site_exchange_rate": true, - "created_at": "2021-05-05T16:00:21-04:00", - "updated_at": "2021-05-05T16:00:21-04:00", - "discount_type": "amount", - "exclude_mid_period_allocations": true, - "apply_on_cancel_at_end_of_period": true, - "coupon_restrictions": [ - { - "id": 0, - "item_type": "Component", - "item_id": 0, - "name": "string", - "handle": "string" - } - ] - } - } - ] - } - } - } - } - } - }, - "operationId": "listCoupons", - "description": "You can retrieve a list of coupons.\n\nIf the coupon is set to `use_site_exchange_rate: true`, it will return pricing based on the current exchange rate. If the flag is set to false, it will return all of the defined prices for each currency.", - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page-default-30.yaml" - }, - { - "schema": { - "$ref": "../components/schemas/Basic-Date-Field.yaml" - }, - "in": "query", - "description": "The field was deprecated: on January 20, 2022. We recommend using filter[date_field] instead to achieve the same result. The type of filter you would like to apply to your search.", - "name": "date_field", - "deprecated": true - }, - { - "schema": { - "type": "string", - "format": "date", - "example": "2011-12-17" - }, - "in": "query", - "name": "start_date", - "description": "The field was deprecated: on January 20, 2022. We recommend using filter[start_date] instead to achieve the same result. The start date (format YYYY-MM-DD) with which to filter the date_field. Returns coupons with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified.", - "deprecated": true - }, - { - "schema": { - "type": "string", - "format": "date" - }, - "in": "query", - "description": "The field was deprecated: on January 20, 2022. We recommend using filter[end_date] instead to achieve the same result. The end date (format YYYY-MM-DD) with which to filter the date_field. Returns coupons with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified.", - "name": "end_date", - "deprecated": true - }, - { - "schema": { - "type": "string", - "format": "date-time", - "example": "2019-06-07T17:20:06Z" - }, - "in": "query", - "description": "The field was deprecated: on January 20, 2022. We recommend using filter[start_datetime] instead to achieve the same result. The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns coupons with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date.", - "name": "start_datetime", - "deprecated": true - }, - { - "schema": { - "type": "string", - "format": "date-time", - "example": "2019-06-07T17:20:06Z" - }, - "in": "query", - "description": "The field was deprecated: on January 20, 2022. We recommend using filter[end_datetime] instead to achieve the same result. The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns coupons with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date.", - "name": "end_datetime", - "deprecated": true - }, - { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [ - 1, - 2, - 3 - ], - "minItems": 1 - }, - "in": "query", - "name": "filter[ids]", - "description": "Allows fetching coupons with matching id based on provided values. Use in query `filter[ids]=1,2,3`.", - "style": "form", - "explode": false - }, - { - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "example": [ - "free", - "free_trial" - ] - }, - "in": "query", - "name": "filter[codes]", - "description": "Allows fetching coupons with matching code based on provided values. Use in query `filter[ids]=1,2,3`.", - "style": "form", - "explode": false - }, - { - "schema": { - "type": "boolean", - "example": true - }, - "in": "query", - "name": "currency_prices", - "description": "When fetching coupons, if you have defined multiple currencies at the site level, you can optionally pass the `?currency_prices=true` query param to include an array of currency price data in the response. Use in query `currency_prices=true`." - }, - { - "schema": { - "type": "string", - "format": "date" - }, - "in": "query", - "name": "filter[end_date]", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns coupons with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. Use in query `filter[end_date]=2011-12-17`." - }, - { - "schema": { - "type": "string", - "format": "date-time", - "example": "2019-06-07T17:20:06Z" - }, - "in": "query", - "name": "filter[end_datetime]", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns coupons with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. Use in query `filter[end_datetime]=2011-12-19T10:15:30+01:00`." - }, - { - "schema": { - "type": "string", - "format": "date", - "example": "2011-12-17" - }, - "in": "query", - "name": "filter[start_date]", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns coupons with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. Use in query `filter[start_date]=2011-12-19`." - }, - { - "schema": { - "type": "string", - "format": "date-time", - "example": "2019-06-07T17:20:06Z" - }, - "in": "query", - "name": "filter[start_datetime]", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns coupons with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. Use in query `filter[start_datetime]=2011-12-19T10:15:30+01:00`." - }, - { - "schema": { - "$ref": "../components/schemas/Basic-Date-Field.yaml" - }, - "in": "query", - "name": "filter[date_field]", - "description": "The type of filter you would like to apply to your search. Use in query `filter[date_field]=updated_at`." - }, - { - "schema": { - "type": "boolean", - "example": true - }, - "in": "query", - "description": "Allows fetching coupons with matching use_site_exchange_rate based on provided value. Use in query `filter[use_site_exchange_rate]=true`.", - "name": "filter[use_site_exchange_rate]" - } - ], - "x-operation-settings": { - "collectParameters": true - } - } - }, - "/product_families/{product_family_id}/coupons/{coupon_id}/usage.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "product_family_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product family to which the coupon belongs" - }, - { - "schema": { - "type": "integer" - }, - "name": "coupon_id", - "in": "path", - "required": true, - "description": "The Chargify id of the coupon" - } - ], - "get": { - "summary": "List Coupon Usages", - "tags": [ - "Coupons" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Coupon-Usage.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "name": "No cost product", - "id": 3903594, - "signups": 0, - "savings": 0, - "savings_in_cents": 0, - "revenue": 0, - "revenue_in_cents": 0 - }, - { - "name": "Product that expires", - "id": 3853680, - "signups": 0, - "savings": 0, - "savings_in_cents": 0, - "revenue": 0, - "revenue_in_cents": 0 - }, - { - "name": "Trial Product", - "id": 3861800, - "signups": 1, - "savings": 30, - "savings_in_cents": 3000, - "revenue": 20, - "revenue_in_cents": 2000 - } - ] - } - } - } - } - } - }, - "operationId": "readCouponUsage", - "description": "This request will provide details about the coupon usage as an array of data hashes, one per product." - } - }, - "/coupons/validate.json": { - "get": { - "summary": "Validate Coupon", - "tags": [ - "Coupons" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Coupon-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "coupon": { - "id": 66, - "name": "Foo Bar", - "code": "YEPPER9993", - "description": "my cool coupon", - "amount_in_cents": 10000, - "product_family_id": 4, - "created_at": "2017-11-07T14:51:52-05:00", - "updated_at": "2017-11-07T15:14:24-05:00", - "start_date": "2017-11-07T14:51:52-05:00", - "end_date": null, - "percentage": null, - "recurring": false, - "duration_period_count": null, - "duration_interval": null, - "duration_interval_unit": null, - "allow_negative_balance": false, - "archived_at": null, - "conversion_limit": null, - "stackable": true, - "compounding_strategy": "full-price", - "coupon_restrictions": [] - } - } - } - } - } - } - }, - "404": { - "description": "Not Found", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Single-String-Error-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": "Coupon code could not be found." - } - } - } - } - } - } - }, - "x-operation-settings": { - "errorTemplates": { - "404": "Not Found: '{$response.body}'" - } - }, - "operationId": "validateCoupon", - "description": "You can verify if a specific coupon code is valid using the `validate` method. This method is useful for validating coupon codes that are entered by a customer. If the coupon is found and is valid, the coupon will be returned with a 200 status code.\n\nIf the coupon is invalid, the status code will be 404 and the response will say why it is invalid. If the coupon is valid, the status code will be 200 and the coupon will be returned. The following reasons for invalidity are supported:\n\n+ Coupon not found\n+ Coupon is invalid\n+ Coupon expired\n\nIf you have more than one product family and if the coupon you are validating does not belong to the first product family in your site, then you will need to specify the product family, either in the url or as a query string param. This can be done by supplying the id or the handle in the `handle:my-family` format.\n\nEg.\n\n```\nhttps://.chargify.com/product_families/handle:/coupons/validate.?code=\n```\n\nOr:\n\n```\nhttps://.chargify.com/coupons/validate.?code=&product_family_id=\n```", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "code", - "required": true, - "description": "The code of the coupon" - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "product_family_id", - "description": "The Chargify id of the product family to which the coupon belongs" - } - ] - } - }, - "/coupons/{coupon_id}/currency_prices.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "coupon_id", - "in": "path", - "required": true, - "description": "The Chargify id of the coupon" - } - ], - "put": { - "summary": "Create / Update Currency Prices", - "tags": [ - "Coupons" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Coupon-Currency-Response.yaml" - } - } - } - } - }, - "operationId": "createOrUpdateCouponCurrencyPrices", - "description": "This endpoint allows you to create and/or update currency prices for an existing coupon. Multiple prices can be created or updated in a single request but each of the currencies must be defined on the site level already and the coupon must be an amount-based coupon, not percentage.\n\nCurrency pricing for coupons must mirror the setup of the primary coupon pricing - if the primary coupon is percentage based, you will not be able to define pricing in non-primary currencies.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Coupon-Currency-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "currency_prices": [ - { - "currency": "EUR", - "price": 10 - }, - { - "currency": "GBP", - "price": 9 - } - ] - } - } - } - } - } - } - } - }, - "/coupons/{coupon_id}/codes.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "coupon_id", - "in": "path", - "required": true, - "description": "The Chargify id of the coupon" - } - ], - "post": { - "summary": "Create Coupon Subcodes", - "tags": [ - "Coupons" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Coupon-Subcodes-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "created_codes": [ - "BALTIMOREFALL", - "ORLANDOFALL", - "DETROITFALL" - ], - "duplicate_codes": [], - "invalid_codes": [] - } - } - } - } - } - } - }, - "operationId": "createCouponSubcodes", - "description": "## Coupon Subcodes Intro\n\nCoupon Subcodes allow you to create a set of unique codes that allow you to expand the use of one coupon.\n\nFor example:\n\nMaster Coupon Code:\n\n+ SPRING2020\n\nCoupon Subcodes:\n\n+ SPRING90210\n+ DP80302\n+ SPRINGBALTIMORE\n\nCoupon subcodes can be administered in the Admin Interface or via the API.\n\nWhen creating a coupon subcode, you must specify a coupon to attach it to using the coupon_id. Valid coupon subcodes are all capital letters, contain only letters and numbers, and do not have any spaces. Lowercase letters will be capitalized before the subcode is created.\n\n## Coupon Subcodes Documentation\n\nFull documentation on how to create coupon subcodes in the Chargify UI can be located [here](https://chargify.zendesk.com/hc/en-us/articles/4407755909531#coupon-codes).\n\nAdditionally, for documentation on how to apply a coupon to a Subscription within the Chargify UI, please see our documentation [here](https://chargify.zendesk.com/hc/en-us/articles/4407884887835#coupon).\n\n## Create Coupon Subcode\n\nThis request allows you to create specific subcodes underneath an existing coupon code.\n\n*Note*: If you are using any of the allowed special characters (\"%\", \"@\", \"+\", \"-\", \"_\", and \".\"), you must encode them for use in the URL.\n\n % to %25\n @ to %40\n + to %2B\n - to %2D\n _ to %5F\n . to %2E\n\nSo, if the coupon subcode is `20%OFF`, the URL to delete this coupon subcode would be: `https://.chargify.com/coupons/567/codes/20%25OFF.`", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subcodes.yaml" - }, - "examples": { - "Example": { - "value": { - "codes": [ - "BALTIMOREFALL", - "ORLANDOFALL", - "DETROITFALL" - ] - } - } - } - } - } - } - }, - "get": { - "summary": "List Coupon Subcodes", - "tags": [ - "Coupons" - ], - "operationId": "listCouponSubcodes", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subcodes.yaml" - }, - "examples": { - "Example": { - "value": { - "codes": [ - "3JU6PR", - "9RO6MP", - "8OG1VV", - "5FL7VV", - "2SV8XK", - "4LW8LH", - "3VL4GZ", - "9UI9XO", - "0LZ0CC", - "8XI9JV", - "9UV5YE", - "3UI4GX", - "6SL5ST", - "9WC8IJ", - "2KA3PZ", - "7WR1VR", - "3VY7MN", - "6KC3KB", - "7DF7YT", - "9FH1ED" - ] - } - } - } - } - } - } - }, - "description": "This request allows you to request the subcodes that are attached to a coupon.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - } - ] - }, - "put": { - "summary": "Update Coupon Subcodes", - "tags": [ - "Coupons" - ], - "operationId": "updateCouponSubcodes", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Coupon-Subcodes-Response.yaml" - } - } - } - } - }, - "description": "You can update the subcodes for the given Coupon via the API with a PUT request to the resource endpoint.\nSend an array of new coupon subcodes.\n\n**Note**: All current subcodes for that Coupon will be deleted first, and replaced with the list of subcodes sent to this endpoint.\nThe response will contain:\n\n+ The created subcodes,\n\n+ Subcodes that were not created because they already exist,\n\n+ Any subcodes not created because they are invalid.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subcodes.yaml" - }, - "examples": { - "Example": { - "value": { - "codes": [ - "AAAA", - "BBBB", - "CCCC" - ] - } - } - } - } - } - } - } - }, - "/coupons/{coupon_id}/codes/{subcode}.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "coupon_id", - "in": "path", - "required": true, - "description": "The Chargify id of the coupon to which the subcode belongs" - }, - { - "schema": { - "type": "string" - }, - "name": "subcode", - "in": "path", - "required": true, - "description": "The subcode of the coupon" - } - ], - "delete": { - "summary": "Delete Coupon Subcode", - "tags": [ - "Coupons" - ], - "responses": { - "200": { - "description": "OK" - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "deleteCouponSubcode", - "description": "## Example\n\nGiven a coupon with an ID of 567, and a coupon subcode of 20OFF, the URL to `DELETE` this coupon subcode would be:\n\n```\nhttp://subdomain.chargify.com/coupons/567/codes/20OFF.\n```\n\nNote: If you are using any of the allowed special characters (“%”, “@”, “+”, “-”, “_”, and “.”), you must encode them for use in the URL.\n\n| Special character | Encoding |\n|-------------------|----------|\n| % | %25 |\n| @ | %40 |\n| + | %2B |\n| – | %2D |\n| _ | %5F |\n| . | %2E |\n\n## Percent Encoding Example\n\nOr if the coupon subcode is 20%OFF, the URL to delete this coupon subcode would be: @https://.chargify.com/coupons/567/codes/20%25OFF." - } - }, - "/events.json": { - "get": { - "summary": "List Events", - "tags": [ - "Events" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "description": "", - "minItems": 1, - "uniqueItems": true, - "items": { - "$ref": "../components/schemas/Event-Response.yaml" - }, - "x-examples": { - "example-1": [ - { - "event": { - "id": 343087780, - "key": "subscription_state_change", - "message": "State changed on Test subscription to Monthly Product from active to past_due", - "subscription_id": 14950962, - "customer_id": 12345678, - "created_at": "2016-10-27T16:42:22-04:00", - "event_specific_data": { - "previous_subscription_state": "active", - "new_subscription_state": "past_due" - } - } - }, - { - "event": { - "id": 343087742, - "key": "billing_date_change", - "message": "Billing date changed on Test's subscription to Monthly Product from 11/27/2016 to 10/27/2016", - "subscription_id": 14950962, - "customer_id": 12345678, - "created_at": "2016-10-27T16:42:19-04:00", - "event_specific_data": null - } - }, - { - "event": { - "id": 343085267, - "key": "statement_closed", - "message": "Statement 79401838 closed (but not settled) for Test's subscription to ANNUAL product", - "subscription_id": 14950975, - "customer_id": 87654321, - "created_at": "2016-10-27T16:40:40-04:00", - "event_specific_data": null - } - } - ] - } - }, - "examples": { - "Example": { - "value": [ - { - "event": { - "id": 343087780, - "key": "subscription_state_change", - "message": "State changed on Test subscription to Monthly Product from active to past_due", - "subscription_id": 14950962, - "customer_id": 12345678, - "created_at": "2016-10-27T16:42:22-04:00", - "event_specific_data": { - "previous_subscription_state": "active", - "new_subscription_state": "past_due" - } - } - }, - { - "event": { - "id": 343087742, - "key": "billing_date_change", - "message": "Billing date changed on Test's subscription to Monthly Product from 11/27/2016 to 10/27/2016", - "subscription_id": 14950962, - "customer_id": 12345678, - "created_at": "2016-10-27T16:42:19-04:00", - "event_specific_data": null - } - }, - { - "event": { - "id": 343085267, - "key": "statement_closed", - "message": "Statement 79401838 closed (but not settled) for Test's subscription to ANNUAL product", - "subscription_id": 14950975, - "customer_id": 87654321, - "created_at": "2016-10-27T16:40:40-04:00", - "event_specific_data": null - } - }, - { - "event": { - "id": 4481, - "key": "custom_field_value_change", - "message": "Custom field (Extra support included) changed for Subscription 117 from 'Yes' to 'No'.", - "subscription_id": 117, - "customer_id": 22334455, - "created_at": "2022-03-24T07:55:06-04:00", - "event_specific_data": { - "event_type": "updated", - "metafield_name": "Extra support included", - "metafield_id": 2, - "old_value": "Yes", - "new_value": "No", - "resource_type": "Subscription", - "resource_id": 117 - } - } - } - ] - } - } - }, - "application/xml": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Event-Response.yaml" - } - } - }, - "multipart/form-data": { - "schema": { - "type": "array", - "items": {} - } - } - } - } - }, - "operationId": "listEvents", - "description": "## Events Intro\n\nChargify Events include various activity that happens around a Site. This information is **especially** useful to track down issues that arise when subscriptions are not created due to errors.\n\nWithin the Chargify UI, \"Events\" are referred to as \"Site Activity\". Full documentation on how to record view Events / Site Activty in the Chargify UI can be located [here](https://chargify.zendesk.com/hc/en-us/articles/4407864698139).\n\n## List Events for a Site\n\nThis method will retrieve a list of events for a site. Use query string filters to narrow down results. You may use the `key` filter as part of your query string to narrow down results.\n\n### Legacy Filters\n\nThe following keys are no longer supported.\n\n+ `payment_failure_recreated`\n+ `payment_success_recreated`\n+ `renewal_failure_recreated`\n+ `renewal_success_recreated`\n+ `zferral_revenue_post_failure` - (Specific to the deprecated Zferral integration)\n+ `zferral_revenue_post_success` - (Specific to the deprecated Zferral integration)\n\n## Event Specific Data\n\nEvent Specific Data\n\nEach event type has its own `event_specific_data` specified.\n\nHere’s an example event for the `subscription_product_change` event:\n\n```\n{\n \"event\": {\n \"id\": 351,\n \"key\": \"subscription_product_change\",\n \"message\": \"Product changed on Marky Mark's subscription from 'Basic' to 'Pro'\",\n \"subscription_id\": 205,\n \"event_specific_data\": {\n \"new_product_id\": 3,\n \"previous_product_id\": 2\n },\n \"created_at\": \"2012-01-30T10:43:31-05:00\"\n }\n}\n```\n\nHere’s an example event for the `subscription_state_change` event:\n\n```\n {\n \"event\": {\n \"id\": 353,\n \"key\": \"subscription_state_change\",\n \"message\": \"State changed on Marky Mark's subscription to Pro from trialing to active\",\n \"subscription_id\": 205,\n \"event_specific_data\": {\n \"new_subscription_state\": \"active\",\n \"previous_subscription_state\": \"trialing\"\n },\n \"created_at\": \"2012-01-30T10:43:33-05:00\"\n }\n }\n```", - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "since_id", - "description": "Returns events with an id greater than or equal to the one specified" - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "max_id", - "description": "Returns events with an id less than or equal to the one specified" - }, - { - "schema": { - "type": "string", - "enum": [ - "asc", - "desc" - ], - "default": "desc" - }, - "in": "query", - "name": "direction", - "description": "The sort direction of the returned events." - }, - { - "$ref": "../components/parameters/event-type-filter.yaml" - }, - { - "schema": { - "$ref": "../components/schemas/List-Events-Date-Field.yaml" - }, - "in": "query", - "name": "date_field", - "description": "The type of filter you would like to apply to your search." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_date", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_date", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_datetime", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_datetime", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date." - } - ], - "x-operation-settings": { - "collectParameters": true - } - } - }, - "/subscriptions/{subscription_id}/events.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "get": { - "summary": "List Events for Subscription", - "tags": [ - "Events" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Event-Response.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "event": { - "id": 344799837, - "key": "statement_settled", - "message": "Statement 79702531 settled successfully for Amelia Example's subscription to Basic Plan", - "subscription_id": 14900541, - "customer_id": 77223344, - "created_at": "2016-11-01T12:41:29-04:00", - "event_specific_data": null - } - }, - { - "event": { - "id": 344799815, - "key": "renewal_success", - "message": "Successful renewal for Amelia Example's subscription to Basic Plan", - "subscription_id": 14900541, - "customer_id": 77223344, - "created_at": "2016-11-01T12:41:28-04:00", - "event_specific_data": { - "product_id": 3792003, - "account_transaction_id": 7590246 - } - } - }, - { - "event": { - "id": 344799705, - "key": "billing_date_change", - "message": "Billing date changed on Amelia Example's subscription to Basic Plan from 11/26/2016 to 11/01/2016", - "subscription_id": 14900541, - "customer_id": 77223344, - "created_at": "2016-11-01T12:41:25-04:00", - "event_specific_data": null - } - } - ] - } - } - } - } - } - }, - "operationId": "listSubscriptionEvents", - "description": "The following request will return a list of events for a subscription.\n\nEach event type has its own `event_specific_data` specified.", - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "since_id", - "description": "Returns events with an id greater than or equal to the one specified" - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "max_id", - "description": "Returns events with an id less than or equal to the one specified" - }, - { - "schema": { - "type": "string", - "enum": [ - "asc", - "desc" - ], - "default": "desc" - }, - "in": "query", - "name": "direction", - "description": "The sort direction of the returned events." - }, - { - "$ref": "../components/parameters/event-type-filter.yaml" - } - ], - "x-operation-settings": { - "collectParameters": true - } - } - }, - "/events/count.json": { - "get": { - "summary": "Read Total Event Count", - "tags": [ - "Events" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Count-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "count": 144 - } - } - } - } - } - } - }, - "operationId": "readEventsCount", - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "since_id", - "description": "Returns events with an id greater than or equal to the one specified" - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "max_id", - "description": "Returns events with an id less than or equal to the one specified" - }, - { - "schema": { - "type": "string", - "enum": [ - "asc", - "desc" - ], - "default": "desc" - }, - "in": "query", - "name": "direction", - "description": "The sort direction of the returned events." - }, - { - "$ref": "../components/parameters/event-type-filter.yaml" - } - ], - "description": "Get a count of all the events for a given site by using this method.", - "x-operation-settings": { - "collectParameters": true - } - } - }, - "/mrr.json": { - "get": { - "summary": "Read MRR", - "tags": [ - "Insights" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/MRR-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "mrr": { - "amount_in_cents": 9915593, - "amount_formatted": "$99,155.93", - "currency": "USD", - "currency_symbol": "$", - "at_time": "2021-02-03T14:23:17-05:00", - "breakouts": { - "plan_amount_in_cents": 9913593, - "plan_amount_formatted": "$99,135.93", - "usage_amount_in_cents": 2000, - "usage_amount_formatted": "$20.00" - } - } - } - } - } - } - } - } - }, - "operationId": "readMrr", - "description": "This endpoint returns your site's current MRR, including plan and usage breakouts.", - "deprecated": true, - "parameters": [ - { - "schema": { - "type": "string", - "format": "date-time" - }, - "in": "query", - "name": "at_time", - "description": "submit a timestamp in ISO8601 format to request MRR for a historic time" - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "subscription_id", - "description": "submit the id of a subscription in order to limit results" - } - ] - } - }, - "/product_families/{product_family_id}/metered_components.json": { - "parameters": [ - { - "$ref": "../components/parameters/product-family-id-path.yaml" - } - ], - "post": { - "summary": "Create Metered Component", - "tags": [ - "Components" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "component": { - "id": 292609, - "name": "Text messages", - "handle": "text-messages", - "pricing_scheme": "per_unit", - "unit_name": "unit", - "unit_price": "10.0", - "product_family_id": 528484, - "product_family_name": "Cloud Compute Servers", - "price_per_unit_in_cents": null, - "kind": "metered_component", - "archived": false, - "taxable": false, - "description": null, - "default_price_point_id": 2944263, - "prices": [ - { - "id": 55423, - "component_id": 30002, - "starting_quantity": 1, - "ending_quantity": null, - "unit_price": "10.0", - "price_point_id": 2944263, - "formatted_unit_price": "$10.00", - "segment_id": null - } - ], - "price_point_count": 1, - "price_points_url": "https://demo-3238403362.chargify.com/components/30002/price_points", - "default_price_point_name": "Original", - "tax_code": null, - "recurring": false, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2024-01-23T06:08:05-05:00", - "updated_at": "2024-01-23T06:08:05-05:00", - "archived_at": null, - "hide_date_range_on_invoice": false, - "allow_fractional_quantities": false, - "use_site_exchange_rate": true, - "item_category": null, - "accounting_code": null - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Name: cannot be blank.", - "Unit name: cannot be blank.", - "At least 1 price bracket must be defined", - "Pricing scheme: cannot be blank.", - "Pricing scheme: is not one of the allowed values." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createMeteredComponent", - "description": "This request will create a component definition of kind **metered_component** under the specified product family. Metered component can then be added and “allocated” for a subscription.\n\nMetered components are used to bill for any type of unit that resets to 0 at the end of the billing period (think daily Google Adwords clicks or monthly cell phone minutes). This is most commonly associated with usage-based billing and many other pricing schemes.\n\nNote that this is different from recurring quantity-based components, which DO NOT reset to zero at the start of every billing period. If you want to bill for a quantity of something that does not change unless you change it, then you want quantity components, instead.\n\nFor more information on components, please see our documentation [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405020625677).", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Metered-Component.yaml" - }, - "examples": { - "Example": { - "value": { - "metered_component": { - "name": "Text messages", - "unit_name": "text message", - "pricing_scheme": "per_unit", - "taxable": false, - "prices": [ - { - "starting_quantity": 1, - "unit_price": 1 - } - ] - } - } - } - } - } - } - } - } - }, - "/product_families/{product_family_id}/quantity_based_components.json": { - "parameters": [ - { - "$ref": "../components/parameters/product-family-id-path.yaml" - } - ], - "post": { - "summary": "Create Quantity Based Component", - "tags": [ - "Components" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "component": { - "id": 292609, - "name": "Text messages", - "handle": "text-messages", - "pricing_scheme": "per_unit", - "unit_name": "unit", - "unit_price": "10.0", - "product_family_id": 528484, - "product_family_name": "Cloud Compute Servers", - "price_per_unit_in_cents": null, - "kind": "quantity_based_component", - "archived": false, - "taxable": false, - "description": null, - "default_price_point_id": 2944263, - "prices": [ - { - "id": 55423, - "component_id": 30002, - "starting_quantity": 1, - "ending_quantity": null, - "unit_price": "10.0", - "price_point_id": 2944263, - "formatted_unit_price": "$10.00", - "segment_id": null - } - ], - "price_point_count": 1, - "price_points_url": "https://demo-3238403362.chargify.com/components/30002/price_points", - "default_price_point_name": "Original", - "tax_code": null, - "recurring": false, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2024-01-23T06:08:05-05:00", - "updated_at": "2024-01-23T06:08:05-05:00", - "archived_at": null, - "hide_date_range_on_invoice": false, - "allow_fractional_quantities": false, - "use_site_exchange_rate": true, - "item_category": null, - "accounting_code": null - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Name: cannot be blank.", - "Unit name: cannot be blank.", - "At least 1 price bracket must be defined", - "Pricing scheme: cannot be blank.", - "Pricing scheme: is not one of the allowed values." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createQuantityBasedComponent", - "description": "This request will create a component definition of kind **quantity_based_component** under the specified product family. Quantity Based component can then be added and “allocated” for a subscription.\n\nWhen defining Quantity Based component, You can choose one of 2 types:\n#### Recurring\nRecurring quantity-based components are used to bill for the number of some unit (think monthly software user licenses or the number of pairs of socks in a box-a-month club). This is most commonly associated with billing for user licenses, number of users, number of employees, etc.\n\n#### One-time\nOne-time quantity-based components are used to create ad hoc usage charges that do not recur. For example, at the time of signup, you might want to charge your customer a one-time fee for onboarding or other services.\n\nThe allocated quantity for one-time quantity-based components immediately gets reset back to zero after the allocation is made.\n\nFor more information on components, please see our documentation [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405020625677).", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Quantity-Component.yaml" - }, - "examples": { - "Quantity Based (per unit)": { - "value": { - "quantity_based_component": { - "name": "Quantity Based Component", - "unit_name": "Component", - "description": "Example of JSON per-unit component example", - "pricing_scheme": "per_unit", - "unit_price": "10", - "taxable": true, - "display_on_hosted_page": true, - "allow_fractional_quantities": true, - "public_signup_page_ids": [ - 323397 - ] - } - } - }, - "Quantity Based (stairstep)": { - "value": { - "quantity_based_component": { - "name": "Quantity Based Component", - "unit_name": "Quantity Based Component", - "description": "Example of JSON stairstep example", - "pricing_scheme": "stairstep", - "taxable": true, - "prices": [ - { - "starting_quantity": "1", - "ending_quantity": "100", - "unit_price": "50" - }, - { - "starting_quantity": "101", - "ending_quantity": "200", - "unit_price": "10" - } - ], - "display_on_hosted_page": true, - "allow_fractional_quantities": true, - "public_signup_page_ids": [ - 323397 - ] - } - } - }, - "Quantity Based (volume)": { - "value": { - "quantity_based_component": { - "name": "Quantity Based Component", - "unit_name": "Quantity Based Component", - "description": "Example of JSON volume component example", - "pricing_scheme": "volume", - "taxable": true, - "prices": [ - { - "starting_quantity": 1, - "ending_quantity": 10, - "unit_price": 10 - }, - { - "starting_quantity": 11, - "ending_quantity": 20, - "unit_price": 5 - } - ], - "display_on_hosted_page": true, - "allow_fractional_quantities": true, - "public_signup_page_ids": [ - 323397 - ] - } - } - }, - "Quantity Based (tiered)": { - "value": { - "quantity_based_component": { - "name": "Quantity Based Component", - "unit_name": "Quantity Based Component", - "description": "Example of JSON for tiered quantity based component", - "taxable": true, - "pricing_scheme": "tiered", - "prices": [ - { - "starting_quantity": 0, - "ending_quantity": 20, - "unit_price": 50 - }, - { - "starting_quantity": 21, - "ending_quantity": 40, - "unit_price": 25 - } - ], - "display_on_hosted_page": true, - "allow_fractional_quantities": true, - "public_signup_page_ids": [ - 323397 - ] - } - } - } - } - } - } - } - } - }, - "/product_families/{product_family_id}/on_off_components.json": { - "parameters": [ - { - "$ref": "../components/parameters/product-family-id-path.yaml" - } - ], - "post": { - "summary": "Create On/Off Component", - "tags": [ - "Components" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "component": { - "id": 292609, - "name": "Test On-Off Component 46124", - "handle": "test-on-off-component-4612422802", - "pricing_scheme": null, - "unit_name": "on/off", - "unit_price": "10.0", - "product_family_id": 528484, - "product_family_name": "Cloud Compute Servers", - "price_per_unit_in_cents": null, - "kind": "on_off_component", - "archived": false, - "taxable": false, - "description": null, - "default_price_point_id": 2944263, - "price_point_count": 1, - "price_points_url": "https://demo-3238403362.chargify.com/components/30002/price_points", - "default_price_point_name": "Original", - "tax_code": null, - "recurring": true, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2024-01-23T06:08:05-05:00", - "updated_at": "2024-01-23T06:08:05-05:00", - "archived_at": null, - "hide_date_range_on_invoice": false, - "allow_fractional_quantities": false, - "use_site_exchange_rate": true, - "item_category": null, - "accounting_code": null - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Name: cannot be blank.", - "Unit price: cannot be blank." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createOnOffComponent", - "description": "This request will create a component definition of kind **on_off_component** under the specified product family. On/Off component can then be added and “allocated” for a subscription.\n\nOn/off components are used for any flat fee, recurring add on (think $99/month for tech support or a flat add on shipping fee).\n\nFor more information on components, please see our documentation [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405020625677).", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-On-Off-Component.yaml" - }, - "examples": { - "On/Off": { - "value": { - "on_off_component": { - "name": "Annual Support Services", - "description": "Prepay for support services", - "taxable": true, - "prices": [ - { - "unit_price": "100.00", - "starting_quantity": "0" - } - ], - "display_on_hosted_page": true, - "public_signup_page_ids": [ - 320495 - ] - } - } - }, - "On/Off with Price Points": { - "value": { - "on_off_component": { - "name": "Annual Support Services", - "description": "Prepay for support services", - "taxable": true, - "prices": [ - { - "unit_price": "100.00", - "starting_quantity": 0 - } - ], - "display_on_hosted_page": true, - "public_signup_page_ids": [ - 320495 - ], - "price_points": [ - { - "name": "Wholesale", - "handle": "wholesale-handle", - "pricing_scheme": "per_unit", - "prices": [ - { - "starting_quantity": 0, - "unit_price": "89.00" - } - ] - } - ] - } - } - }, - "On/Off with Default Proration Schemes": { - "value": { - "on_off_component": { - "name": "Annual Support Services", - "description": "Prepay for support services", - "taxable": true, - "prices": [ - { - "unit_price": "100.00", - "starting_quantity": 0 - } - ], - "display_on_hosted_page": true, - "public_signup_page_ids": [ - 320495 - ], - "upgrade_charge": "full", - "downgrade_credit": "prorated" - } - } - } - } - } - } - } - } - }, - "/product_families/{product_family_id}/prepaid_usage_components.json": { - "parameters": [ - { - "$ref": "../components/parameters/product-family-id-path.yaml" - } - ], - "post": { - "summary": "Create Prepaid Usage Component", - "tags": [ - "Components" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "component": { - "id": 292609, - "name": "Test Prepaid Component 98505", - "handle": "test-prepaid-component-9850584842", - "pricing_scheme": "per_unit", - "unit_name": "unit", - "unit_price": "10.0", - "product_family_id": 528484, - "product_family_name": "Test Product Family 27791", - "price_per_unit_in_cents": null, - "kind": "prepaid_usage_component", - "archived": false, - "taxable": false, - "description": "Description for: Test Prepaid Component 98505", - "default_price_point_id": 2944263, - "overage_prices": [ - { - "id": 55964, - "component_id": 30427, - "starting_quantity": 1, - "ending_quantity": null, - "unit_price": "1.0", - "price_point_id": 2944756, - "formatted_unit_price": "$1.00", - "segment_id": null - } - ], - "prices": [ - { - "id": 55963, - "component_id": 30427, - "starting_quantity": 1, - "ending_quantity": null, - "unit_price": "1.0", - "price_point_id": 2944756, - "formatted_unit_price": "$1.00", - "segment_id": null - } - ], - "price_point_count": 1, - "price_points_url": "https://demo-3238403362.chargify.com/components/30002/price_points", - "default_price_point_name": "Original", - "tax_code": null, - "recurring": true, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2024-01-23T06:08:05-05:00", - "updated_at": "2024-01-23T06:08:05-05:00", - "archived_at": null, - "hide_date_range_on_invoice": false, - "allow_fractional_quantities": false, - "use_site_exchange_rate": true, - "item_category": null, - "accounting_code": null - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "errors": [ - "Handle must be unique within a Site.", - "Name: must be unique - that value has been taken." - ] - } - }, - "Example-2": { - "value": { - "errors": [ - "Name: cannot be blank.", - "Pricing scheme: cannot be blank.", - "Pricing scheme: is not one of the allowed values." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createPrepaidUsageComponent", - "description": "This request will create a component definition of kind **prepaid_usage_component** under the specified product family. Prepaid component can then be added and “allocated” for a subscription.\n\nPrepaid components allow customers to pre-purchase units that can be used up over time on their subscription. In a sense, they are the mirror image of metered components; while metered components charge at the end of the period for the amount of units used, prepaid components are charged for at the time of purchase, and we subsequently keep track of the usage against the amount purchased.\n\nFor more information on components, please see our documentation [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405020625677).", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Prepaid-Component.yaml" - }, - "examples": { - "Prepaid Usage": { - "value": { - "prepaid_usage_component": { - "name": "Minutes", - "unit_name": "minutes", - "unit_price": 2, - "pricing_scheme": "per_unit", - "rollover_prepaid_remainder": true, - "renew_prepaid_allocation": true, - "expiration_interval": 15, - "expiration_interval_unit": "day", - "overage_pricing": { - "pricing_scheme": "stairstep", - "prices": [ - { - "starting_quantity": 1, - "ending_quantity": 100, - "unit_price": 3 - }, - { - "starting_quantity": 101, - "unit_price": 5 - } - ] - } - } - } - } - } - } - } - } - } - }, - "/product_families/{product_family_id}/event_based_components.json": { - "parameters": [ - { - "$ref": "../components/parameters/product-family-id-path.yaml" - } - ], - "post": { - "summary": "Create Event Based Component", - "tags": [ - "Components" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "component": { - "id": 1489581, - "name": "stripeCharges", - "handle": null, - "pricing_scheme": null, - "unit_name": "charge", - "unit_price": null, - "product_family_id": 1517093, - "product_family_name": "Billing Plans", - "price_per_unit_in_cents": null, - "kind": "event_based_component", - "archived": false, - "taxable": false, - "description": null, - "default_price_point_id": null, - "prices": [], - "price_point_count": 0, - "price_points_url": "https://staging.chargify.com/components/1489581/price_points", - "default_price_point_name": "Original", - "tax_code": null, - "recurring": false, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2021-10-12T07:33:24-05:00", - "updated_at": "2021-10-12T07:33:24-05:00", - "archived_at": null, - "hide_date_range_on_invoice": false, - "allow_fractional_quantities": false, - "use_site_exchange_rate": null, - "item_category": null, - "accounting_code": null, - "event_based_billing_metric_id": 1163 - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Metric: cannot be blank.", - "Name: cannot be blank.", - "Unit name: cannot be blank.", - "Pricing scheme: cannot be blank.", - "Pricing scheme: is not one of the allowed values." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createEventBasedComponent", - "description": "This request will create a component definition of kind **event_based_component** under the specified product family. Event-based component can then be added and “allocated” for a subscription.\n\nEvent-based components are similar to other component types, in that you define the component parameters (such as name and taxability) and the pricing. A key difference for the event-based component is that it must be attached to a metric. This is because the metric provides the component with the actual quantity used in computing what and how much will be billed each period for each subscription.\n\nSo, instead of reporting usage directly for each component (as you would with metered components), the usage is derived from analysis of your events. \n\nFor more information on components, please see our documentation [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405020625677).", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Ebb-Component.yaml" - }, - "examples": { - "Event Based Component": { - "value": { - "event_based_component": { - "name": "Component Name", - "unit_name": "string", - "description": "string", - "handle": "some_handle", - "taxable": true, - "pricing_scheme": "per_unit", - "prices": [ - { - "starting_quantity": 1, - "unit_price": "0.49" - } - ], - "event_based_billing_metric_id": 123 - } - } - } - } - } - } - } - } - }, - "/components/lookup.json": { - "get": { - "summary": "Find Component", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "component": { - "id": 399853, - "name": "Annual Support Services", - "pricing_scheme": null, - "unit_name": "on/off", - "unit_price": "100.0", - "product_family_id": 997233, - "price_per_unit_in_cents": null, - "kind": "on_off_component", - "archived": false, - "taxable": true, - "description": "Prepay for support services", - "default_price_point_id": 121003, - "price_point_count": 4, - "price_points_url": "https://general-goods.chargify.com/components/399853/price_points", - "tax_code": "D0000000", - "recurring": true, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2019-08-02T05:54:53-04:00", - "default_price_point_name": "Original", - "product_family_name": "Chargify" - } - } - } - } - } - } - } - }, - "operationId": "findComponent", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "required": true, - "name": "handle", - "description": "The handle of the component to find" - } - ], - "description": "This request will return information regarding a component having the handle you provide. You can identify your components with a handle so you don't have to save or reference the IDs we generate." - } - }, - "/product_families/{product_family_id}/components/{component_id}.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "product_family_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product family to which the component belongs" - }, - { - "schema": { - "type": "string", - "pattern": "/\\A(?:\\d+|handle:(?:uuid:|[a-z])(?:\\w|-)+)\\z/" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "Either the Chargify id of the component or the handle for the component prefixed with `handle:`" - } - ], - "get": { - "summary": "Read Component", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "component": { - "id": 399853, - "name": "Annual Support Services", - "pricing_scheme": null, - "unit_name": "on/off", - "unit_price": "100.0", - "product_family_id": 997233, - "price_per_unit_in_cents": null, - "kind": "on_off_component", - "archived": false, - "taxable": true, - "description": "Prepay for support services", - "default_price_point_id": 121003, - "price_point_count": 4, - "price_points_url": "https://general-goods.chargify.com/components/399853/price_points", - "tax_code": "D0000000", - "recurring": true, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2019-08-02T05:54:53-04:00", - "default_price_point_name": "Original", - "product_family_name": "Chargify" - } - } - } - } - } - } - } - }, - "operationId": "readComponent", - "description": "This request will return information regarding a component from a specific product family.\n\nYou may read the component by either the component's id or handle. When using the handle, it must be prefixed with `handle:`." - }, - "put": { - "summary": "Update Product Family Component", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "component": { - "id": 399853, - "name": "Annual Support Services", - "pricing_scheme": null, - "unit_name": "on/off", - "unit_price": "100.0", - "product_family_id": 997233, - "price_per_unit_in_cents": null, - "kind": "on_off_component", - "archived": false, - "taxable": true, - "description": "Prepay for support services", - "default_price_point_id": 121003, - "price_point_count": 4, - "price_points_url": "https://general-goods.chargify.com/components/399853/price_points", - "tax_code": "D0000000", - "recurring": true, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2019-08-02T05:54:53-04:00", - "default_price_point_name": "Original", - "product_family_name": "Chargify" - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Name: cannot be blank." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updateProductFamilyComponent", - "description": "This request will update a component from a specific product family.\n\nYou may read the component by either the component's id or handle. When using the handle, it must be prefixed with `handle:`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Component-Request.yaml" - } - } - } - } - }, - "delete": { - "summary": "Archive Component", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component.yaml" - }, - "examples": { - "Example": { - "value": { - "id": 25407138, - "name": "cillum aute", - "pricing_scheme": "stairstep", - "unit_name": "nulla in", - "unit_price": "Excepteur veniam", - "product_family_id": -56705047, - "kind": "prepaid_usage_component", - "archived": true, - "taxable": false, - "description": "reprehenderit laborum qui fugiat", - "default_price_point_id": -64328176, - "price_point_count": 15252407, - "price_points_url": "dolor mollit consequat", - "tax_code": "ea nisi", - "recurring": false, - "created_at": "2016-11-08T16:22:26-05:00", - "default_price_point_name": "cupidatat Lorem non aliqua", - "product_family_name": "do elit", - "hide_date_range_on_invoice": false - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Component cannot be archived. Please make sure it hasn't already been archived." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "archiveComponent", - "description": "Sending a DELETE request to this endpoint will archive the component. All current subscribers will be unffected; their subscription/purchase will continue to be charged as usual." - } - }, - "/components.json": { - "get": { - "summary": "List Components", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Component-Response.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "component": { - "id": 399850, - "name": "$1.00 component", - "pricing_scheme": "per_unit", - "unit_name": "Component", - "unit_price": "1.0", - "product_family_id": 997233, - "price_per_unit_in_cents": null, - "kind": "quantity_based_component", - "archived": false, - "taxable": false, - "description": "Component", - "default_price_point_id": 121000, - "prices": [ - { - "id": 630687, - "component_id": 399850, - "starting_quantity": 1, - "ending_quantity": null, - "unit_price": "1.0", - "price_point_id": 121000, - "formatted_unit_price": "$1.00" - } - ], - "price_point_count": 2, - "price_points_url": "https://general-goods.chargify.com/components/399850/price_points", - "tax_code": null, - "recurring": true, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2019-08-01T09:35:38-04:00", - "default_price_point_name": "Original", - "product_family_name": "Chargify", - "use_site_exchange_rate": true - } - }, - { - "component": { - "id": 399853, - "name": "Annual Support Services", - "pricing_scheme": null, - "unit_name": "on/off", - "unit_price": "100.0", - "product_family_id": 997233, - "price_per_unit_in_cents": null, - "kind": "on_off_component", - "archived": false, - "taxable": true, - "description": "Prepay for support services", - "default_price_point_id": 121003, - "price_point_count": 4, - "price_points_url": "https://general-goods.chargify.com/components/399853/price_points", - "tax_code": "D0000000", - "recurring": true, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2019-08-01T09:35:37-04:00", - "default_price_point_name": "Original", - "product_family_name": "Chargify", - "use_site_exchange_rate": true - } - }, - { - "component": { - "id": 386937, - "name": "Cancellation fee", - "pricing_scheme": null, - "unit_name": "on/off", - "unit_price": "35.0", - "product_family_id": 997233, - "price_per_unit_in_cents": null, - "kind": "on_off_component", - "archived": false, - "taxable": false, - "description": "", - "default_price_point_id": 108307, - "price_point_count": 1, - "price_points_url": "https://general-goods.chargify.com/components/386937/price_points", - "tax_code": null, - "recurring": true, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2019-08-01T09:35:38-04:00", - "default_price_point_name": "Original", - "product_family_name": "Chargify", - "use_site_exchange_rate": true - } - } - ] - } - } - } - } - } - }, - "operationId": "listComponents", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "schema": { - "$ref": "../components/schemas/Basic-Date-Field.yaml" - }, - "in": "query", - "name": "date_field", - "description": "The type of filter you would like to apply to your search." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_date", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_date", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_datetime", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_datetime", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. optional" - }, - { - "schema": { - "type": "boolean" - }, - "in": "query", - "name": "include_archived", - "description": "Include archived items" - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "1", - "2", - "3" - ] - }, - "in": "query", - "name": "filter[ids]", - "description": "Allows fetching components with matching id based on provided value. Use in query `filter[ids]=1,2,3`.", - "style": "form", - "explode": false - }, - { - "schema": { - "type": "boolean", - "example": true - }, - "in": "query", - "name": "filter[use_site_exchange_rate]", - "description": "Allows fetching components with matching use_site_exchange_rate based on provided value (refers to default price point). Use in query `filter[use_site_exchange_rate]=true`." - } - ], - "description": "This request will return a list of components for a site." - } - }, - "/components/{component_id}.json": { - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "The id or handle of the component" - } - ], - "put": { - "summary": "Update Component", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "component": { - "id": 399853, - "name": "Annual Support Services", - "pricing_scheme": null, - "unit_name": "on/off", - "unit_price": "100.0", - "product_family_id": 997233, - "price_per_unit_in_cents": null, - "kind": "on_off_component", - "archived": false, - "taxable": true, - "description": "Prepay for support services", - "default_price_point_id": 121003, - "price_point_count": 4, - "price_points_url": "https://general-goods.chargify.com/components/399853/price_points", - "tax_code": "D0000000", - "recurring": true, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2019-08-02T05:54:53-04:00", - "default_price_point_name": "Original", - "product_family_name": "Chargify" - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Name: cannot be blank." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updateComponent", - "description": "This request will update a component.\n\nYou may read the component by either the component's id or handle. When using the handle, it must be prefixed with `handle:`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Component-Request.yaml" - } - } - } - } - } - }, - "/components/{component_id}/price_points/{price_point_id}/default.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "The Chargify id of the component to which the price point belongs" - }, - { - "schema": { - "type": "integer" - }, - "name": "price_point_id", - "in": "path", - "required": true, - "description": "The Chargify id of the price point" - } - ], - "put": { - "summary": "Promote Price Point to Default", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "component": { - "id": 292609, - "name": "Text messages", - "pricing_scheme": "stairstep", - "unit_name": "text message", - "unit_price": null, - "product_family_id": 528484, - "price_per_unit_in_cents": null, - "kind": "metered_component", - "archived": false, - "taxable": false, - "description": null, - "created_at": "2019-08-02T05:54:53-04:00", - "prices": [ - { - "id": 47, - "component_id": 292609, - "starting_quantity": 1, - "ending_quantity": null, - "unit_price": "1.0", - "price_point_id": 173, - "formatted_unit_price": "$1.00" - } - ], - "default_price_point_name": "Original" - } - } - } - } - } - } - } - }, - "operationId": "promoteComponentPricePointToDefault", - "description": "Sets a new default price point for the component. This new default will apply to all new subscriptions going forward - existing subscriptions will remain on their current price point.\n\nSee [Price Points Documentation](https://chargify.zendesk.com/hc/en-us/articles/4407755865883#price-points) for more information on price points and moving subscriptions between price points.\n\nNote: Custom price points are not able to be set as the default for a component." - } - }, - "/product_families/{product_family_id}/components.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "product_family_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product family" - } - ], - "get": { - "summary": "List Components for Product Family", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Component-Response.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "component": { - "id": 399850, - "name": "$1.00 component", - "pricing_scheme": "per_unit", - "unit_name": "Component", - "unit_price": "1.0", - "product_family_id": 997233, - "price_per_unit_in_cents": null, - "kind": "quantity_based_component", - "archived": false, - "taxable": false, - "description": "Component", - "default_price_point_id": 121000, - "prices": [ - { - "id": 630687, - "component_id": 399850, - "starting_quantity": 1, - "ending_quantity": null, - "unit_price": "1.0", - "price_point_id": 121000, - "formatted_unit_price": "$1.00" - } - ], - "price_point_count": 2, - "price_points_url": "https://general-goods.chargify.com/components/399850/price_points", - "tax_code": null, - "recurring": true, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2019-08-01T09:35:38-04:00", - "default_price_point_name": "Original", - "product_family_name": "Chargify", - "use_site_exchange_rate": true - } - }, - { - "component": { - "id": 399853, - "name": "Annual Support Services", - "pricing_scheme": null, - "unit_name": "on/off", - "unit_price": "100.0", - "product_family_id": 997233, - "price_per_unit_in_cents": null, - "kind": "on_off_component", - "archived": false, - "taxable": true, - "description": "Prepay for support services", - "default_price_point_id": 121003, - "price_point_count": 4, - "price_points_url": "https://general-goods.chargify.com/components/399853/price_points", - "tax_code": "D0000000", - "recurring": true, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2019-08-01T09:35:37-04:00", - "default_price_point_name": "Original", - "product_family_name": "Chargify", - "use_site_exchange_rate": true - } - }, - { - "component": { - "id": 386937, - "name": "Cancellation fee", - "pricing_scheme": null, - "unit_name": "on/off", - "unit_price": "35.0", - "product_family_id": 997233, - "price_per_unit_in_cents": null, - "kind": "on_off_component", - "archived": false, - "taxable": false, - "description": "", - "default_price_point_id": 108307, - "price_point_count": 1, - "price_points_url": "https://general-goods.chargify.com/components/386937/price_points", - "tax_code": null, - "recurring": true, - "upgrade_charge": null, - "downgrade_credit": null, - "created_at": "2019-08-01T09:35:38-04:00", - "default_price_point_name": "Original", - "product_family_name": "Chargify", - "use_site_exchange_rate": true - } - } - ] - } - } - } - } - } - }, - "operationId": "listComponentsForProductFamily", - "description": "This request will return a list of components for a particular product family.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "schema": { - "type": "boolean" - }, - "in": "query", - "name": "include_archived", - "description": "Include archived items." - }, - { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [ - 1, - 2 - ] - }, - "style": "form", - "explode": false, - "in": "query", - "description": "Allows fetching components with matching id based on provided value. Use in query `filter[ids]=1,2`.", - "name": "filter[ids]" - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "$ref": "../components/schemas/Basic-Date-Field.yaml" - }, - "in": "query", - "name": "date_field", - "description": "The type of filter you would like to apply to your search. Use in query `date_field=created_at`." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_date", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_datetime", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. optional." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_date", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_datetime", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date." - }, - { - "schema": { - "type": "boolean", - "example": true - }, - "in": "query", - "description": "Allows fetching components with matching use_site_exchange_rate based on provided value (refers to default price point). Use in query `filter[use_site_exchange_rate]=true`.", - "name": "filter[use_site_exchange_rate]" - } - ] - } - }, - "/components/{component_id}/price_points.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "The Chargify id of the component" - } - ], - "post": { - "summary": "Create Component Price Point", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Price-Point-Response.yaml" - } - } - } - } - }, - "operationId": "createComponentPricePoint", - "description": "This endpoint can be used to create a new price point for an existing component.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Component-Price-Point-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "price_point": { - "name": "Wholesale", - "handle": "wholesale-handle", - "pricing_scheme": "stairstep", - "use_site_exchange_rate": false, - "prices": [ - { - "starting_quantity": "1", - "ending_quantity": "100", - "unit_price": "5.00" - }, - { - "starting_quantity": "101", - "ending_quantity": null, - "unit_price": "4.00" - } - ] - } - } - }, - "Prepaid Usage Component": { - "value": { - "price_point": { - "name": "MSRP", - "handle": "msrp", - "pricing_scheme": "stairstep", - "renew_prepaid_allocation": false, - "rollover_prepaid_remainder": true, - "expiration_interval": 2, - "expiration_interval_unit": "month", - "prices": [ - { - "starting_quantity": 1, - "ending_quantity": 100, - "unit_price": 5 - }, - { - "starting_quantity": 101, - "ending_quantity": null, - "unit_price": 4 - } - ], - "overage_pricing": { - "pricing_scheme": "stairstep", - "prices": [ - { - "starting_quantity": 1, - "ending_quantity": 100, - "unit_price": 4 - } - ] - } - } - } - }, - "On Off Component": { - "value": { - "price_point": { - "name": "Special Pricing", - "handle": "special", - "pricing_scheme": "per_unit", - "prices": [ - { - "starting_quantity": 1, - "unit_price": 5 - } - ] - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Component Price Points", - "tags": [ - "Components" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Price-Points-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "price_points": [ - { - "id": 80, - "default": false, - "name": "Wholesale Two", - "pricing_scheme": "per_unit", - "component_id": 74, - "handle": "wholesale-two", - "archived_at": null, - "created_at": "2017-07-05T13:55:40-04:00", - "updated_at": "2017-07-05T13:55:40-04:00", - "prices": [ - { - "id": 121, - "component_id": 74, - "starting_quantity": 1, - "ending_quantity": null, - "unit_price": "5.0" - } - ] - }, - { - "id": 81, - "default": false, - "name": "MSRP", - "pricing_scheme": "per_unit", - "component_id": 74, - "handle": "msrp", - "archived_at": null, - "created_at": "2017-07-05T13:55:40-04:00", - "updated_at": "2017-07-05T13:55:40-04:00", - "prices": [ - { - "id": 122, - "component_id": 74, - "starting_quantity": 1, - "ending_quantity": null, - "unit_price": "4.0" - } - ] - } - ] - } - } - } - } - } - } - }, - "operationId": "listComponentPricePoints", - "description": "Use this endpoint to read current price points that are associated with a component.\n\nYou may specify the component by using either the numeric id or the `handle:gold` syntax.\n\nWhen fetching a component's price points, if you have defined multiple currencies at the site level, you can optionally pass the `?currency_prices=true` query param to include an array of currency price data in the response.\n\nIf the price point is set to `use_site_exchange_rate: true`, it will return pricing based on the current exchange rate. If the flag is set to false, it will return all of the defined prices for each currency.", - "parameters": [ - { - "schema": { - "type": "boolean" - }, - "in": "query", - "name": "currency_prices", - "description": "Include an array of currency price data" - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "$ref": "../components/parameters/price-point-type-filter.yaml" - } - ], - "x-operation-settings": { - "collectParameters": true - } - } - }, - "/components/{component_id}/price_points/bulk.json": { - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "The Chargify id of the component for which you want to fetch price points." - } - ], - "post": { - "summary": "Bulk Create Component Price Points", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Price-Points-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "price_points": [ - { - "id": 80, - "default": false, - "name": "Wholesale Two", - "pricing_scheme": "per_unit", - "component_id": 74, - "handle": "wholesale-two", - "archived_at": null, - "created_at": "2017-07-05T13:55:40-04:00", - "updated_at": "2017-07-05T13:55:40-04:00", - "prices": [ - { - "id": 121, - "component_id": 74, - "starting_quantity": 1, - "ending_quantity": null, - "unit_price": "5.0" - } - ] - }, - { - "id": 81, - "default": false, - "name": "MSRP", - "pricing_scheme": "per_unit", - "component_id": 74, - "handle": "msrp", - "archived_at": null, - "created_at": "2017-07-05T13:55:40-04:00", - "updated_at": "2017-07-05T13:55:40-04:00", - "prices": [ - { - "id": 122, - "component_id": 74, - "starting_quantity": 1, - "ending_quantity": null, - "unit_price": "4.0" - } - ] - } - ] - } - } - } - } - } - } - }, - "operationId": "bulkCreateComponentPricePoints", - "description": "Use this endpoint to create multiple component price points in one request.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Component-Price-Points-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "price_points": [ - { - "name": "Wholesale", - "handle": "wholesale", - "pricing_scheme": "per_unit", - "prices": [ - { - "starting_quantity": 1, - "unit_price": 5 - } - ] - }, - { - "name": "MSRP", - "handle": "msrp", - "pricing_scheme": "per_unit", - "prices": [ - { - "starting_quantity": 1, - "unit_price": 4 - } - ] - }, - { - "name": "Special Pricing", - "handle": "special", - "pricing_scheme": "per_unit", - "prices": [ - { - "starting_quantity": 1, - "unit_price": 5 - } - ] - } - ] - } - } - } - } - } - } - } - }, - "/components/{component_id}/price_points/{price_point_id}.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "The Chargify id of the component to which the price point belongs" - }, - { - "schema": { - "type": "integer" - }, - "name": "price_point_id", - "in": "path", - "required": true, - "description": "The Chargify id of the price point" - } - ], - "put": { - "summary": "Update Component Price Point", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Price-Point-Response.yaml" - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-Array-Map-Response.yaml" - }, - "examples": { - "Invalid price id": { - "value": { - "errors": { - "base": [ - "all prices must belong to the price point" - ] - } - } - }, - "Invalid price definition": { - "value": { - "errors": { - "prices": [ - "Successive brackets may not have gaps in quantity (i.e. if one bracket ends at quantity 10, the next must begin at quantity 11)" - ] - } - } - }, - "Missing price": { - "value": { - "errors": { - "prices": [ - "At least 1 price bracket must be defined" - ] - } - } - }, - "Overlapping prices": { - "value": { - "errors": { - "prices": [ - "There cannot be any overlapping bracket ranges" - ] - } - } - }, - "Invalid handle": { - "value": { - "errors": { - "handle": [ - "Handle: This handle is already in use." - ] - } - } - }, - "Invalid quantity": { - "value": { - "errors": { - "prices.ending_quantity": [ - "Ending quantity: must be greater than the low end bracket quantity, if given" - ] - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updateComponentPricePoint", - "description": "When updating a price point, it's prices can be updated as well by creating new prices or editing / removing existing ones.\n\nPassing in a price bracket without an `id` will attempt to create a new price.\n\nIncluding an `id` will update the corresponding price, and including the `_destroy` flag set to true along with the `id` will remove that price.\n\nNote: Custom price points cannot be updated directly. They must be edited through the Subscription.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Component-Price-Point-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "price_point": { - "name": "Default", - "prices": [ - { - "id": 1, - "ending_quantity": 100, - "unit_price": 5 - }, - { - "id": 2, - "_destroy": true - }, - { - "starting_quantity": 101, - "unit_price": 4 - } - ] - } - } - } - } - } - } - } - }, - "delete": { - "summary": "Archive Component Price Point", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Price-Point-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "price_point": { - "id": 79, - "default": false, - "name": "Wholesale", - "pricing_scheme": "stairstep", - "component_id": 74, - "handle": "wholesale-handle", - "archived_at": "2017-07-06T15:04:00-04:00", - "created_at": "2017-07-05T13:44:30-04:00", - "updated_at": "2017-07-05T13:44:30-04:00", - "prices": [ - { - "id": 119, - "component_id": 74, - "starting_quantity": 1, - "ending_quantity": 100, - "unit_price": "5.0" - }, - { - "id": 120, - "component_id": 74, - "starting_quantity": 101, - "ending_quantity": null, - "unit_price": "4.0" - } - ] - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Price point is already archived." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "archiveComponentPricePoint", - "description": "A price point can be archived at any time. Subscriptions using a price point that has been archived will continue using it until they're moved to another price point." - } - }, - "/components/{component_id}/price_points/{price_point_id}/unarchive.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "The Chargify id of the component to which the price point belongs" - }, - { - "schema": { - "type": "integer" - }, - "name": "price_point_id", - "in": "path", - "required": true, - "description": "The Chargify id of the price point" - } - ], - "put": { - "summary": "Unarchive Component Price Point", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Price-Point-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "price_point": { - "id": 79, - "default": false, - "name": "Wholesale", - "pricing_scheme": "stairstep", - "component_id": 74, - "handle": "wholesale-handle", - "archived_at": null, - "created_at": "2017-07-05T13:44:30-04:00", - "updated_at": "2017-07-05T13:44:30-04:00", - "prices": [ - { - "id": 119, - "component_id": 74, - "starting_quantity": 1, - "ending_quantity": 100, - "unit_price": "5.0" - }, - { - "id": 120, - "component_id": 74, - "starting_quantity": 101, - "ending_quantity": null, - "unit_price": "4.0" - } - ] - } - } - } - } - } - } - } - }, - "operationId": "unarchiveComponentPricePoint", - "description": "Use this endpoint to unarchive a component price point." - } - }, - "/price_points/{price_point_id}/currency_prices.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "price_point_id", - "in": "path", - "required": true, - "description": "The Chargify id of the price point" - } - ], - "post": { - "summary": "Create Currency Prices", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Currency-Prices-Response.yaml" - }, - "examples": { - "example-1": { - "value": { - "currency_prices": [ - { - "id": 100, - "currency": "EUR", - "price": "123", - "formatted_price": "€123,00", - "price_id": 32669, - "price_point_id": 25554 - } - ] - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-Array-Map-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": { - "currency_prices[0].currency": [ - "Currency: cannot be blank.", - "Currency: is not one of the allowed values." - ] - } - } - } - } - } - } - } - }, - "operationId": "createCurrencyPrices", - "description": "This endpoint allows you to create currency prices for a given currency that has been defined on the site level in your settings.\n\nWhen creating currency prices, they need to mirror the structure of your primary pricing. For each price level defined on the component price point, there should be a matching price level created in the given currency.\n\nNote: Currency Prices are not able to be created for custom price points.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Currency-Prices-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "currency_prices": [ - { - "currency": "EUR", - "price": 50, - "price_id": 20 - }, - { - "currency": "EUR", - "price": 40, - "price_id": 21 - } - ] - } - } - } - } - } - } - }, - "put": { - "summary": "Update Currency Prices", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Component-Currency-Prices-Response.yaml" - }, - "examples": { - "example-1": { - "value": { - "currency_prices": [ - { - "id": 100, - "currency": "EUR", - "price": "123", - "formatted_price": "€123,00", - "price_id": 32669, - "price_point_id": 25554 - } - ] - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-Array-Map-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": { - "currency_prices[0].currency": [ - "Pricing already exists for this currency." - ] - } - } - } - } - } - } - } - }, - "operationId": "updateCurrencyPrices", - "description": "This endpoint allows you to update currency prices for a given currency that has been defined on the site level in your settings.\n\nNote: Currency Prices are not able to be updated for custom price points.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Currency-Prices-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "currency_prices": [ - { - "id": 100, - "price": 51 - }, - { - "id": 101, - "price": 41 - } - ] - } - } - } - } - } - } - } - }, - "/mrr_movements.json": { - "get": { - "summary": "List MRR Movements", - "tags": [ - "Insights" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-MRR-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "mrr": { - "page": 0, - "per_page": 10, - "total_pages": 80, - "total_entries": 791, - "currency": "USD", - "currency_symbol": "$", - "movements": [ - { - "timestamp": "2014-12-03T13:59:46-05:00", - "amount_in_cents": 2173, - "amount_formatted": "$21.73", - "description": "Awesome Company signed up for Super Product ($21.73/mo)", - "category": "new_business", - "breakouts": { - "plan_amount_in_cents": 2173, - "plan_amount_formatted": "$21.73", - "usage_amount_in_cents": 0, - "usage_amount_formatted": "$0.00" - }, - "line_items": [ - { - "product_id": 306386, - "component_id": 0, - "price_point_id": 3856987, - "name": "Cached Queries", - "mrr": 2173, - "mrr_movements": [ - { - "amount": 2173, - "category": "new_business", - "subscriber_delta": 0, - "lead_delta": 0 - } - ], - "quantity": 1, - "prev_quantity": 0, - "recurring": true - } - ], - "subscription_id": 12355, - "subscriber_name": "Amy Smith" - } - ] - } - } - } - } - } - } - } - }, - "operationId": "listMrrMovements", - "deprecated": true, - "description": "This endpoint returns your site's MRR movements.\n\n## Understanding MRR movements\n\nThis endpoint will aid in accessing your site's [MRR Report](https://chargify.zendesk.com/hc/en-us/articles/4407838249627) data.\n\nWhenever a subscription event occurs that causes your site's MRR to change (such as a signup or upgrade), we record an MRR movement. These records are accessible via the MRR Movements endpoint.\n\nEach MRR Movement belongs to a subscription and contains a timestamp, category, and an amount. `line_items` represent the subscription's product configuration at the time of the movement.\n\n### Plan & Usage Breakouts\n\nIn the MRR Report UI, we support a setting to [include or exclude](https://chargify.zendesk.com/hc/en-us/articles/4407838249627#displaying-component-based-metered-usage-in-mrr) usage revenue. In the MRR APIs, responses include `plan` and `usage` breakouts.\n\nPlan includes revenue from:\n* Products\n* Quantity-Based Components\n* On/Off Components\n\nUsage includes revenue from:\n* Metered Components\n* Prepaid Usage Components", - "parameters": [ - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "subscription_id", - "description": "optionally filter results by subscription" - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page-default-10.yaml" - }, - { - "$ref": "../components/parameters/sort-direction.yaml" - } - ], - "x-operation-settings": { - "collectParameters": true - } - } - }, - "/product_families/{product_family_id}/products.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "product_family_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product family to which the product belongs" - } - ], - "post": { - "summary": "Create Product", - "tags": [ - "Products" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "examples": { - "Example": { - "value": { - "product": { - "id": 4364984, - "name": "Gold Plan", - "handle": "gold", - "description": "This is our gold plan.", - "accounting_code": "123", - "request_credit_card": true, - "created_at": "2016-11-04T16:31:15-04:00", - "updated_at": "2016-11-04T16:31:15-04:00", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "expiration_interval_unit": null, - "initial_charge_in_cents": null, - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": null, - "archived_at": null, - "require_credit_card": true, - "return_params": null, - "taxable": false, - "update_return_url": null, - "initial_charge_after_trial": false, - "version_number": 1, - "update_return_params": null, - "product_family": { - "id": 527890, - "name": "Acme Projects", - "description": "", - "handle": "billing-plans", - "accounting_code": null - }, - "public_signup_pages": [ - { - "id": 301078, - "return_url": null, - "return_params": null, - "url": "https://general-goods.chargify.com/subscribe/ftgbpq7f5qpr/gold" - } - ], - "product_price_point_name": "Default" - } - } - } - }, - "schema": { - "$ref": "../components/schemas/Product-Response.yaml" - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Name: cannot be blank." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createProduct", - "description": "Use this method to create a product within your Chargify site.\n\n+ [Products Documentation](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405561405709)\n+ [Changing a Subscription's Product](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404225334669-Product-Changes-Migrations)", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-or-Update-Product-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "product": { - "name": "Gold Plan", - "handle": "gold", - "description": "This is our gold plan.", - "accounting_code": "123", - "require_credit_card": true, - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "auto_create_signup_page": true, - "tax_code": "D0000000" - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Products for Product Family", - "operationId": "listProductsForProductFamily", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Product-Response.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "product": { - "id": 3801242, - "name": "Free product", - "handle": "zero-dollar-product", - "description": "", - "accounting_code": "", - "request_credit_card": true, - "expiration_interval": null, - "expiration_interval_unit": "never", - "created_at": "2016-04-21T16:08:39-04:00", - "updated_at": "2016-08-03T11:27:53-04:00", - "price_in_cents": 10000, - "interval": 1, - "interval_unit": "month", - "initial_charge_in_cents": 0, - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": false, - "return_params": "", - "taxable": false, - "update_return_url": "", - "initial_charge_after_trial": false, - "version_number": 4, - "update_return_params": "", - "product_family": { - "id": 527890, - "name": "Acme Projects", - "description": "", - "handle": "billing-plans", - "accounting_code": null - }, - "public_signup_pages": [ - { - "id": 283460, - "return_url": null, - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/smcc4j3d2w6h/zero-dollar-product" - } - ], - "product_price_point_name": "Default", - "use_site_exchange_rate": true - } - }, - { - "product": { - "id": 3858146, - "name": "Calendar Billing Product", - "handle": "calendar-billing-product", - "description": "", - "accounting_code": "", - "request_credit_card": true, - "expiration_interval": null, - "expiration_interval_unit": "never", - "created_at": "2016-07-05T13:07:38-04:00", - "updated_at": "2016-07-05T13:07:38-04:00", - "price_in_cents": 10000, - "interval": 1, - "interval_unit": "month", - "initial_charge_in_cents": null, - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": true, - "return_params": "", - "taxable": false, - "update_return_url": "", - "initial_charge_after_trial": false, - "version_number": 1, - "update_return_params": "", - "product_family": { - "id": 527890, - "name": "Acme Projects", - "description": "", - "handle": "billing-plans", - "accounting_code": null - }, - "public_signup_pages": [ - { - "id": 289193, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/gxdbfxzxhcjq/calendar-billing-product" - } - ], - "product_price_point_name": "Default", - "use_site_exchange_rate": true - } - } - ] - } - } - } - } - }, - "404": { - "description": "Not Found", - "content": { - "application/json": { - "schema": { - "type": "string" - }, - "examples": { - "Example": { - "value": "A valid product_family_id is required" - } - } - } - } - } - }, - "description": "This method allows to retrieve a list of Products belonging to a Product Family.", - "x-operation-settings": { - "errorTemplates": { - "404": "Not Found:'{$response.body}'" - }, - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "$ref": "../components/parameters/basic-date-field.yaml" - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_date", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns products with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_date", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns products with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_datetime", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns products with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_datetime", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns products with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date." - }, - { - "schema": { - "type": "boolean" - }, - "in": "query", - "name": "include_archived", - "description": "Include archived products" - }, - { - "schema": { - "$ref": "../components/schemas/List-Products-Include.yaml" - }, - "in": "query", - "name": "include", - "description": "Allows including additional data in the response. Use in query `include=prepaid_product_price_point`." - }, - { - "schema": { - "$ref": "../components/schemas/Include-Not-Null.yaml" - }, - "in": "query", - "name": "filter[prepaid_product_price_point][product_price_point_id]", - "description": "Allows fetching products only if a prepaid product price point is present or not. To use this filter you also have to include the following param in the request `include=prepaid_product_price_point`. Use in query `filter[prepaid_product_price_point][product_price_point_id]=not_null`." - }, - { - "schema": { - "type": "boolean", - "example": true - }, - "in": "query", - "name": "filter[use_site_exchange_rate]", - "description": "Allows fetching products with matching use_site_exchange_rate based on provided value (refers to default price point). Use in query `filter[use_site_exchange_rate]=true`." - } - ], - "tags": [ - "Product Families" - ] - } - }, - "/products/{product_id}.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "product_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product" - } - ], - "get": { - "summary": "Read Product", - "tags": [ - "Products" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Product-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "product": { - "id": 4535635, - "name": "Paid Annual Seats", - "handle": "paid-annual-seats", - "description": "Paid annual seats for our commercial enterprise product", - "accounting_code": "paid-annual-seats", - "request_credit_card": true, - "expiration_interval": 1, - "expiration_interval_unit": "day", - "created_at": "2017-08-25T10:25:31-05:00", - "updated_at": "2018-01-16T12:58:04-06:00", - "price_in_cents": 10000, - "interval": 12, - "interval_unit": "month", - "initial_charge_in_cents": 4900, - "trial_price_in_cents": 1000, - "trial_interval": 14, - "trial_interval_unit": "day", - "archived_at": null, - "require_credit_card": true, - "return_params": "id={subscription_id}&ref={customer_reference}", - "taxable": true, - "update_return_url": "http://www.example.com", - "tax_code": "D0000000", - "initial_charge_after_trial": false, - "version_number": 4, - "update_return_params": "id={subscription_id}&ref={customer_reference}", - "product_family": { - "id": 1025627, - "name": "Acme Products", - "description": "", - "handle": "acme-products", - "accounting_code": null - }, - "public_signup_pages": [], - "product_price_point_name": "Default" - } - } - } - } - } - } - } - }, - "operationId": "readProduct", - "description": "This endpoint allows you to read the current details of a product that you've created in Chargify." - }, - "put": { - "summary": "Update Product", - "tags": [ - "Products" - ], - "operationId": "updateProduct", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Product-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "product": { - "id": 4365034, - "name": "Platinum Plan", - "handle": "platinum", - "description": "This is our platinum plan.", - "accounting_code": "123", - "request_credit_card": true, - "created_at": "2016-11-04T16:34:29-04:00", - "updated_at": "2016-11-04T16:37:11-04:00", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "initial_charge_in_cents": null, - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": null, - "archived_at": null, - "require_credit_card": true, - "return_params": null, - "taxable": false, - "update_return_url": null, - "initial_charge_after_trial": false, - "version_number": 1, - "update_return_params": null, - "product_family": { - "id": 527890, - "name": "Acme Projects", - "description": "", - "handle": "billing-plans", - "accounting_code": null - }, - "public_signup_pages": [ - { - "id": 301079, - "return_url": null, - "return_params": null, - "url": "https://general-goods.chargify.com/subscribe/wgyd96tb5pj9/platinum" - } - ], - "product_price_point_name": "Original" - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Name: cannot be blank." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "description": "Use this method to change aspects of an existing product.\n\n### Input Attributes Update Notes\n\n+ `update_return_params` The parameters we will append to your `update_return_url`. See Return URLs and Parameters\n\n### Product Price Point\n\nUpdating a product using this endpoint will create a new price point and set it as the default price point for this product. If you should like to update an existing product price point, that must be done separately.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-or-Update-Product-Request.yaml" - } - } - } - } - }, - "delete": { - "summary": "Archive Product", - "tags": [ - "Products" - ], - "operationId": "archiveProduct", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Product-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "product": { - "id": 4535638, - "name": "Business Monthly", - "handle": null, - "description": "Business Monthly", - "accounting_code": "", - "request_credit_card": true, - "expiration_interval": null, - "expiration_interval_unit": "never", - "created_at": "2017-08-25T10:25:31-05:00", - "updated_at": "2018-01-16T13:02:44-06:00", - "price_in_cents": 4900, - "interval": 1, - "interval_unit": "month", - "initial_charge_in_cents": null, - "trial_price_in_cents": 0, - "trial_interval": 1, - "trial_interval_unit": "day", - "archived_at": "2018-01-16T13:02:44-06:00", - "require_credit_card": false, - "return_params": "", - "taxable": false, - "update_return_url": "", - "tax_code": "", - "initial_charge_after_trial": false, - "version_number": 1, - "update_return_params": "", - "product_family": { - "id": 1025627, - "name": "Acme Products", - "description": "", - "handle": "acme-products", - "accounting_code": null - }, - "public_signup_pages": [], - "product_price_point_name": "Default" - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Product cannot be archived." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "description": "Sending a DELETE request to this endpoint will archive the product. All current subscribers will be unffected; their subscription/purchase will continue to be charged monthly.\n\nThis will restrict the option to chose the product for purchase via the Billing Portal, as well as disable Public Signup Pages for the product." - } - }, - "/products/handle/{api_handle}.json": { - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "api_handle", - "in": "path", - "required": true, - "description": "The handle of the product" - } - ], - "get": { - "summary": "Read Product by Handle", - "tags": [ - "Products" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Product-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "product": { - "id": 3903594, - "name": "No cost product", - "handle": "no-cost-product", - "description": "", - "accounting_code": "", - "request_credit_card": true, - "expiration_interval": null, - "expiration_interval_unit": "never", - "created_at": "2016-09-02T17:11:29-04:00", - "updated_at": "2016-11-30T11:46:13-05:00", - "price_in_cents": 0, - "interval": 1, - "interval_unit": "month", - "initial_charge_in_cents": null, - "trial_price_in_cents": 5, - "trial_interval": 1, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": false, - "return_params": "reference=5678", - "taxable": false, - "update_return_url": "", - "initial_charge_after_trial": false, - "version_number": 1, - "update_return_params": "reference=5678", - "product_family": { - "id": 527890, - "name": "Acme Projects", - "description": "", - "handle": "billing-plans", - "accounting_code": null - }, - "public_signup_pages": [ - { - "id": 281174, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/xgdxtk4vhtbz/no-cost-product" - }, - { - "id": 282270, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/xxqmrgtsbd9k/no-cost-product" - }, - { - "id": 291587, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/pvhwss7zjjnh/no-cost-product" - }, - { - "id": 294832, - "return_url": "http://www.example.com/", - "return_params": "engine=md7a", - "url": "https://general-goods.chargify.com/subscribe/m6tbcq4mcgpw/no-cost-product" - } - ], - "product_price_point_name": "Default" - } - } - } - } - } - } - } - }, - "operationId": "readProductByHandle", - "description": "This method allows to retrieve a Product object by its `api_handle`." - } - }, - "/product_families.json": { - "post": { - "summary": "Create Product Family", - "tags": [ - "Product Families" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Product-Family-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "product_family": { - "id": 933860, - "name": "Acme Projects", - "description": "Amazing project management tool", - "handle": "acme-projects", - "accounting_code": null - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "API Handle: must be unique - that value has been taken." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createProductFamily", - "description": "This method will create a Product Family within your Chargify site. Create a Product Family to act as a container for your products, components and coupons.\n\nFull documentation on how Product Families operate within the Chargify UI can be located [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405369633421).", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Product-Family-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "product_family": { - "name": "Acme Projects", - "description": "Amazing project management tool" - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Product Families", - "tags": [ - "Product Families" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Product-Family-Response.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "product_family": { - "id": 37, - "name": "Acme Projects", - "description": null, - "handle": "acme-projects", - "accounting_code": null, - "created_at": "2013-02-20T15:05:51-07:00", - "updated_at": "2013-02-20T15:05:51-07:00" - } - }, - { - "product_family": { - "id": 155, - "name": "Bat Family", - "description": "Another family.", - "handle": "bat-family", - "accounting_code": null, - "created_at": "2014-04-16T12:41:13-06:00", - "updated_at": "2014-04-16T12:41:13-06:00" - } - } - ] - } - } - } - } - } - }, - "operationId": "listProductFamilies", - "description": "This method allows to retrieve a list of Product Families for a site.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/basic-date-field.yaml" - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_date", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns products with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_date", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns products with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_datetime", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns products with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_datetime", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns products with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date." - } - ] - } - }, - "/product_families/{id}.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "id", - "in": "path", - "required": true, - "description": "The Chargify id of the product family" - } - ], - "get": { - "summary": "Read Product Family", - "tags": [ - "Product Families" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Product-Family-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "product_family": { - "id": 527890, - "name": "Acme Projects", - "description": "", - "handle": "billing-plans", - "accounting_code": null - } - } - } - } - } - } - } - }, - "operationId": "readProductFamily", - "description": "This method allows to retrieve a Product Family via the `product_family_id`. The response will contain a Product Family object.\n\nThe product family can be specified either with the id number, or with the `handle:my-family` format." - } - }, - "/products/{product_id}/price_points.json": { - "parameters": [ - { - "schema": { - "type": [ - "integer", - "string" - ] - }, - "name": "product_id", - "in": "path", - "required": true, - "description": "The id or handle of the product. When using the handle, it must be prefixed with `handle:`" - } - ], - "post": { - "summary": "Create Product Price Point", - "tags": [ - "Product: Price Points" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Product-Price-Point-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "price_point": { - "id": 283, - "name": "Educational", - "handle": "educational", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "trial_price_in_cents": 4900, - "trial_interval": 1, - "trial_interval_unit": "month", - "trial_type": "payment_expected", - "initial_charge_in_cents": 120000, - "initial_charge_after_trial": false, - "expiration_interval": 12, - "expiration_interval_unit": "month", - "product_id": 901, - "archived_at": "2023-11-30T06:37:20-05:00", - "created_at": "2023-11-27T06:37:20-05:00", - "updated_at": "2023-11-27T06:37:20-05:00" - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Product-Price-Point-Error-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "errors": { - "price_point": "can't be blank" - } - } - }, - "Example-2": { - "value": { - "errors": { - "interval": [ - "Recurring Interval: cannot be blank." - ], - "interval_unit": [ - "Interval unit: cannot be blank.", - "Interval unit: must be 'month' or 'day'." - ], - "name": [ - "Name: cannot be blank." - ], - "price": [ - "Price: is not a number." - ], - "price_in_cents": [ - "Price in cents: cannot be blank." - ] - } - } - }, - "Example-3": { - "value": { - "errors": { - "interval": [ - "Recurring Interval: must be greater than or equal to 1." - ] - } - } - }, - "Example-4": { - "value": { - "errors": { - "price": [ - "Price: must be greater than or equal to 0." - ] - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createProductPricePoint", - "description": "[Product Price Point Documentation](https://chargify.zendesk.com/hc/en-us/articles/4407755824155)", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Product-Price-Point-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "price_point": { - "name": "Educational", - "handle": "educational", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "trial_price_in_cents": 4900, - "trial_interval": 1, - "trial_interval_unit": "month", - "trial_type": "payment_expected", - "initial_charge_in_cents": 120000, - "initial_charge_after_trial": false, - "expiration_interval": 12, - "expiration_interval_unit": "month" - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Product Price Points", - "tags": [ - "Product: Price Points" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Product-Price-Points-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "price_points": [ - { - "id": 283, - "name": "Educational", - "handle": "educational", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "trial_price_in_cents": 4900, - "trial_interval": 1, - "trial_interval_unit": "month", - "trial_type": "payment_expected", - "initial_charge_in_cents": 120000, - "initial_charge_after_trial": false, - "expiration_interval": 12, - "expiration_interval_unit": "month", - "product_id": 901, - "archived_at": "2023-11-30T06:37:20-05:00", - "created_at": "2023-11-27T06:37:20-05:00", - "updated_at": "2023-11-27T06:37:20-05:00" - } - ] - } - } - } - } - } - } - }, - "operationId": "listProductPricePoints", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "schema": { - "type": "integer", - "maximum": 200, - "default": 10 - }, - "in": "query", - "name": "per_page", - "description": "This parameter indicates how many records to fetch in each request. Default value is 10. The maximum allowed values is 200; any per_page value over 200 will be changed to 200." - }, - { - "schema": { - "type": "boolean" - }, - "in": "query", - "name": "currency_prices", - "description": "When fetching a product's price points, if you have defined multiple currencies at the site level, you can optionally pass the ?currency_prices=true query param to include an array of currency price data in the response. If the product price point is set to use_site_exchange_rate: true, it will return pricing based on the current exchange rate. If the flag is set to false, it will return all of the defined prices for each currency." - }, - { - "$ref": "../components/parameters/price-point-type-filter.yaml" - } - ], - "description": "Use this endpoint to retrieve a list of product price points." - } - }, - "/products/{product_id}/price_points/{price_point_id}.json": { - "parameters": [ - { - "schema": { - "type": [ - "integer", - "string" - ] - }, - "name": "product_id", - "in": "path", - "required": true, - "description": "The id or handle of the product. When using the handle, it must be prefixed with `handle:`" - }, - { - "schema": { - "type": [ - "integer", - "string" - ] - }, - "name": "price_point_id", - "in": "path", - "required": true, - "description": "The id or handle of the price point. When using the handle, it must be prefixed with `handle:`" - } - ], - "put": { - "summary": "Update Product Price Point", - "tags": [ - "Product: Price Points" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Product-Price-Point-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "price_point": { - "id": 283, - "name": "Educational", - "handle": "educational", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "trial_price_in_cents": 4900, - "trial_interval": 1, - "trial_interval_unit": "month", - "trial_type": "payment_expected", - "initial_charge_in_cents": 120000, - "initial_charge_after_trial": false, - "expiration_interval": 12, - "expiration_interval_unit": "month", - "product_id": 901, - "archived_at": "2023-11-30T06:37:20-05:00", - "created_at": "2023-11-27T06:37:20-05:00", - "updated_at": "2023-11-27T06:37:20-05:00" - } - } - } - } - } - } - } - }, - "operationId": "updateProductPricePoint", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Product-Price-Point-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "price_point": { - "handle": "educational", - "price_in_cents": 1250 - } - } - } - } - } - } - }, - "description": "Use this endpoint to update a product price point.\n\nNote: Custom product price points are not able to be updated." - }, - "get": { - "summary": "Read Product Price Point", - "tags": [ - "Product: Price Points" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Product-Price-Point-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "price_point": { - "id": 283, - "name": "Educational", - "handle": "educational", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "trial_price_in_cents": 4900, - "trial_interval": 1, - "trial_interval_unit": "month", - "trial_type": "payment_expected", - "initial_charge_in_cents": 120000, - "initial_charge_after_trial": false, - "expiration_interval": 12, - "expiration_interval_unit": "month", - "product_id": 901, - "archived_at": "2023-11-30T06:37:20-05:00", - "created_at": "2023-11-27T06:37:20-05:00", - "updated_at": "2023-11-27T06:37:20-05:00" - } - } - } - } - } - } - } - }, - "operationId": "readProductPricePoint", - "description": "Use this endpoint to retrieve details for a specific product price point.", - "parameters": [ - { - "schema": { - "type": "boolean" - }, - "in": "query", - "name": "currency_prices", - "description": "When fetching a product's price points, if you have defined multiple currencies at the site level, you can optionally pass the ?currency_prices=true query param to include an array of currency price data in the response. If the product price point is set to use_site_exchange_rate: true, it will return pricing based on the current exchange rate. If the flag is set to false, it will return all of the defined prices for each currency." - } - ] - }, - "delete": { - "summary": "Archive Product Price Point", - "tags": [ - "Product: Price Points" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Product-Price-Point-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "price_point": { - "id": 283, - "name": "Educational", - "handle": "educational", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "trial_price_in_cents": 4900, - "trial_interval": 1, - "trial_interval_unit": "month", - "trial_type": "payment_expected", - "initial_charge_in_cents": 120000, - "initial_charge_after_trial": false, - "expiration_interval": 12, - "expiration_interval_unit": "month", - "product_id": 901, - "archived_at": "2023-11-30T06:37:20-05:00", - "created_at": "2023-11-27T06:37:20-05:00", - "updated_at": "2023-11-27T06:37:20-05:00" - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Cannot archive the default price point." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "archiveProductPricePoint", - "description": "Use this endpoint to archive a product price point." - } - }, - "/products/{product_id}/price_points/{price_point_id}/unarchive.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "product_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product to which the price point belongs" - }, - { - "schema": { - "type": "integer" - }, - "name": "price_point_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product price point" - } - ], - "patch": { - "summary": "Unarchive Product Price Point", - "tags": [ - "Product: Price Points" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Product-Price-Point-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "price_point": { - "id": 283, - "name": "Educational", - "handle": "educational", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "trial_price_in_cents": 4900, - "trial_interval": 1, - "trial_interval_unit": "month", - "trial_type": "payment_expected", - "initial_charge_in_cents": 120000, - "initial_charge_after_trial": false, - "expiration_interval": 12, - "expiration_interval_unit": "month", - "product_id": 901, - "archived_at": "2023-11-30T06:37:20-05:00", - "created_at": "2023-11-27T06:37:20-05:00", - "updated_at": "2023-11-27T06:37:20-05:00" - } - } - } - } - } - } - } - }, - "operationId": "unarchiveProductPricePoint", - "description": "Use this endpoint to unarchive an archived product price point." - } - }, - "/products/{product_id}/price_points/{price_point_id}/default.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "product_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product to which the price point belongs" - }, - { - "schema": { - "type": "integer" - }, - "name": "price_point_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product price point" - } - ], - "patch": { - "summary": "Promote Product Price Point to Default", - "tags": [ - "Product: Price Points" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Product-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "product": { - "id": 29778, - "name": "Educational", - "handle": "educational", - "description": null, - "accounting_code": null, - "request_credit_card": true, - "expiration_interval": 12, - "expiration_interval_unit": "month", - "created_at": "2023-12-01T06:56:12-05:00", - "updated_at": "2023-12-01T06:56:26-05:00", - "price_in_cents": 100, - "interval": 2, - "interval_unit": "month", - "initial_charge_in_cents": 120000, - "trial_price_in_cents": 4900, - "trial_interval": 1, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": true, - "return_params": null, - "taxable": false, - "update_return_url": null, - "tax_code": null, - "initial_charge_after_trial": false, - "version_number": 1, - "update_return_params": null, - "default_product_price_point_id": 32395, - "request_billing_address": false, - "require_billing_address": false, - "require_shipping_address": false, - "use_site_exchange_rate": true, - "item_category": null, - "product_price_point_id": 32395, - "product_price_point_name": "Default", - "product_price_point_handle": "uuid:8c878f50-726e-013c-c71b-0286551bb34f", - "product_family": { - "id": 933860, - "name": "Acme Projects", - "description": "Amazing project management tool", - "handle": "acme-projects", - "accounting_code": null, - "created_at": "2023-12-01T06:56:12-05:00", - "updated_at": "2023-12-01T06:56:12-05:00" - }, - "public_signup_pages": [] - } - } - } - } - } - } - } - }, - "operationId": "promoteProductPricePointToDefault", - "description": "Use this endpoint to make a product price point the default for the product.\n\nNote: Custom product price points are not able to be set as the default for a product." - } - }, - "/products/{product_id}/price_points/bulk.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "product_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product to which the price points belong" - } - ], - "post": { - "summary": "Bulk Create Product Price Points", - "tags": [ - "Product: Price Points" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Bulk-Create-Product-Price-Points-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "price_points": [ - { - "id": 283, - "name": "Educational", - "handle": "educational", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "trial_price_in_cents": 4900, - "trial_interval": 1, - "trial_interval_unit": "month", - "trial_type": "payment_expected", - "initial_charge_in_cents": 120000, - "initial_charge_after_trial": false, - "expiration_interval": 12, - "expiration_interval_unit": "month", - "product_id": 901, - "archived_at": "2023-11-30T06:37:20-05:00", - "created_at": "2023-11-27T06:37:20-05:00", - "updated_at": "2023-11-27T06:37:20-05:00" - } - ] - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-Array-Map.yaml" - }, - "examples": { - "Example-1": { - "value": { - "price_points[0].currency_prices": [ - "Currency prices: is invalid." - ], - "price_points[0].interval": [ - "Recurring Interval: cannot be blank." - ], - "price_points[0].interval_unit": [ - "Interval unit: must be 'month' or 'day'." - ], - "price_points[0].name": [ - "Name: cannot be blank." - ], - "price_points[0].price": [ - "Price: is not a number." - ], - "price_points[0].price_in_cents": [ - "Price in cents: cannot be blank." - ], - "price_points[1].currency_prices": [ - "Currency prices: is invalid." - ], - "price_points[1].interval": [ - "Recurring Interval: cannot be blank." - ], - "price_points[1].interval_unit": [ - "Interval unit: must be 'month' or 'day'." - ], - "price_points[1].name": [ - "Name: cannot be blank." - ], - "price_points[1].price": [ - "Price: is not a number." - ], - "price_points[1].price_in_cents": [ - "Price in cents: cannot be blank." - ] - } - }, - "Example-2": { - "value": { - "price_points[0].interval": [ - "Recurring Interval: must be greater than or equal to 1." - ] - } - }, - "Example-3": { - "value": { - "price_points[0].currency_prices": [ - "Currency prices: is invalid." - ], - "price_points[0].price": [ - "Price: must be greater than or equal to 0." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "bulkCreateProductPricePoints", - "description": "Use this endpoint to create multiple product price points in one request.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Bulk-Create-Product-Price-Points-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "price_points": [ - { - "name": "Educational", - "handle": "educational", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "trial_price_in_cents": 4900, - "trial_interval": 1, - "trial_interval_unit": "month", - "trial_type": "payment_expected", - "initial_charge_in_cents": 120000, - "initial_charge_after_trial": false, - "expiration_interval": 12, - "expiration_interval_unit": "month" - }, - { - "name": "More Educational", - "handle": "more-educational", - "price_in_cents": 2000, - "interval": 1, - "interval_unit": "month", - "trial_price_in_cents": 4900, - "trial_interval": 1, - "trial_interval_unit": "month", - "trial_type": "payment_expected", - "initial_charge_in_cents": 120000, - "initial_charge_after_trial": false, - "expiration_interval": 12, - "expiration_interval_unit": "month" - } - ] - } - } - } - } - } - } - } - }, - "/product_price_points/{product_price_point_id}/currency_prices.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "product_price_point_id", - "in": "path", - "required": true, - "description": "The Chargify id of the product price point" - } - ], - "post": { - "summary": "Create Product Currency Prices", - "tags": [ - "Product: Price Points" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Currency-Prices-Response.yaml" - }, - "examples": { - "example-1": { - "value": { - "currency_prices": [ - { - "id": 100, - "currency": "EUR", - "price": 123, - "formatted_price": "€123,00", - "product_price_point_id": 32669, - "role": "baseline" - } - ] - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-Array-Map-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": { - "base": [ - "This product price point requires that prices are defined for: [baseline]." - ] - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createProductCurrencyPrices", - "description": "This endpoint allows you to create currency prices for a given currency that has been defined on the site level in your settings.\n\nWhen creating currency prices, they need to mirror the structure of your primary pricing. If the product price point defines a trial and/or setup fee, each currency must also define a trial and/or setup fee.\n\nNote: Currency Prices are not able to be created for custom product price points.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Product-Currency-Prices-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "currency_prices": [ - { - "currency": "EUR", - "price": 60, - "role": "baseline" - }, - { - "currency": "EUR", - "price": 30, - "role": "trial" - }, - { - "currency": "EUR", - "price": 100, - "role": "initial" - } - ] - } - } - } - } - }, - "description": "" - } - }, - "put": { - "summary": "Update Product Currency Prices", - "tags": [ - "Product: Price Points" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Currency-Prices-Response.yaml" - }, - "examples": { - "example-1": { - "value": { - "currency_prices": [ - { - "id": 123, - "currency": "EUR", - "price": 100, - "formatted_price": "€123,00", - "product_price_point_id": 32669, - "role": "baseline" - } - ] - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-Array-Map-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": { - "base": [ - "This product price point requires that prices are defined for: [baseline]." - ] - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updateProductCurrencyPrices", - "description": "This endpoint allows you to update the `price`s of currency prices for a given currency that exists on the product price point.\n\nWhen updating the pricing, it needs to mirror the structure of your primary pricing. If the product price point defines a trial and/or setup fee, each currency must also define a trial and/or setup fee.\n\nNote: Currency Prices are not able to be updated for custom product price points.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Currency-Prices-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "currency_prices": [ - { - "id": 200, - "price": 15 - }, - { - "id": 201, - "price": 5 - } - ] - } - } - } - } - } - } - } - }, - "/payment_profiles.json": { - "post": { - "summary": "Create Payment Profile", - "tags": [ - "Payment Profiles" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Payment-Profile-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "payment_profile": { - "first_name": "Jessica", - "last_name": "Test", - "card_type": "visa", - "masked_card_number": "XXXX-XXXX-XXXX-1111", - "expiration_month": 10, - "expiration_year": 2018, - "customer_id": 19195410, - "current_vault": "bogus", - "vault_token": "1", - "billing_address": "123 Main St.", - "billing_city": "Boston", - "billing_state": "MA", - "billing_zip": "02120", - "billing_country": "US", - "customer_vault_token": null, - "billing_address_2": null, - "payment_type": "credit_card", - "site_gateway_setting_id": 1, - "gateway_handle": "handle", - "disabled": false - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "errors": [ - "Credit card expiration month: cannot be blank.", - "Credit card expiration year: cannot be blank.", - "Credit card number: cannot be blank." - ] - } - }, - "Example-2": { - "value": { - "errors": [ - "Chargify token not found" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createPaymentProfile", - "description": "Use this endpoint to create a payment profile for a customer.\n\nPayment Profiles house the credit card, ACH (Authorize.Net or Stripe only,) or PayPal (Braintree only,) data for a customer. The payment information is attached to the customer within Chargify, as opposed to the Subscription itself.\n\nYou must include a customer_id so that Chargify will attach it to the customer entry. If no customer_id is included the API will return a 404.\n\n## Create a Payment Profile for ACH usage\n\nIf you would like to create a payment method that is a Bank Account applicable for ACH payments use the following:\n```json\n{\n\"payment_profile\": {\n \"customer_id\": [Valid-Customer-ID],\n \"bank_name\": \"Best Bank\",\n \"bank_routing_number\": \"021000089\",\n \"bank_account_number\": \"111111111111\",\n \"bank_account_type\": \"checking\",\n \"bank_account_holder_type\": \"business\",\n \"payment_type\": \"bank_account\"\n }\n}\n```\n\n## Taxable Subscriptions\n\nIf your subscriber pays taxes on their purchased product, and you are attempting to create or update the `payment_profile`, complete address information is required. For information on required address formatting to allow your subscriber to be taxed, please see our documentation [here](https://developers.chargify.com/docs/developer-docs/d2e9e34db740e-signups#taxes)\n\n## Payment Profile Documentation\n\nFull documentation on how Payment Profiles operate within Chargify can be located under the following links:\n\n+ [Subscriber Payment Details](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405212558349-Customers-Reference#customers-reference-0-0)\n+ [Self Service Pages](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404759627021) (Allows credit card updates by Subscriber)\n+ [Public Signup Pages payment settings](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405267754381-Individual-Page-Settings#credit-card-settings)\n\n## Create a Payment Profile with a Chargify.js token\n\n```json\n{\n \"payment_profile\": {\n \"customer_id\": 1036,\n \"chargify_token\": \"tok_w68qcpnftyv53jk33jv6wk3w\"\n }\n}\n```\n\n## Active Payment Methods\n\nCreating a new payment profile for a Customer via the API will not make that Payment Profile current for any of the Customer’s Subscriptions. In order to utilize the payment profile as the default, it must be set as the default payment profile for the subscription or subscription group.\n\n## Requirements\n\nEither the full_number, expiration_month, and expiration_year or if you have an existing vault_token from your gateway, that vault_token and the current_vault are required.\nPassing in the vault_token and current_vault are only allowed when creating a new payment profile.\n\n### Taxable Subscriptions\n\nIf your subscriber pays taxes on their purchased product, and you are attempting to create or update the `payment_profile`, complete address information is required. For information on required address formatting to allow your subscriber to be taxed, please see our documentation [here](https://developers.chargify.com/docs/developer-docs/d2e9e34db740e-signups#taxes)\n\n## BraintreeBlue\nSome merchants use Braintree JavaScript libraries directly and then pass `payment_method_nonce` and/or `paypal_email` to create a payment profile. This implementation is deprecated and does not handle 3D Secure. Instead, we have provided [Chargify.js](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDI0-overview) which is continuously improved and supports Credit Cards (along with 3D Secure), PayPal and ApplePay payment types.\n\n## GoCardless\n\nFor more information on GoCardless, please view the following resources:\n\n+ [Full documentation on GoCardless](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404501889677)\n\n+ [Using Chargify.js with GoCardless - minimal example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#minimal-example-with-direct-debit-gocardless-gateway)\n\n+ [Using Chargify.js with GoCardless - full example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#full-example-with-direct-debit-gocardless-gateway)\n\n### GoCardless with Local Bank Details\n\nFollowing examples create customer, bank account and mandate in GoCardless:\n\n```json\n{\n \"payment_profile\": {\n \"customer_id\": \"Valid-Customer-ID\",\n \"bank_name\": \"Royal Bank of France\",\n \"bank_account_number\": \"0000000\",\n \"bank_routing_number\": \"0003\",\n \"bank_branch_code\": \"00006\",\n \"payment_type\": \"bank_account\",\n \"billing_address\": \"20 Place de la Gare\",\n \"billing_city\": \"Colombes\",\n \"billing_state\": \"Île-de-France\",\n \"billing_zip\": \"92700\",\n \"billing_country\": \"FR\"\n }\n}\n```\n\n### GoCardless with IBAN\n\n```json\n{\n \"payment_profile\": {\n \"customer_id\": \"24907598\",\n \"bank_name\": \"French Bank\",\n \"bank_iban\": \"FR1420041010050500013M02606\",\n \"payment_type\": \"bank_account\",\n \"billing_address\": \"20 Place de la Gare\",\n \"billing_city\": \"Colombes\",\n \"billing_state\": \"Île-de-France\",\n \"billing_zip\": \"92700\",\n \"billing_country\": \"FR\"\n }\n}\n```\n\n### Importing GoCardless\n\nIf the customer, bank account, and mandate already exist in GoCardless, a payment profile can be created by using the IDs. In order to create masked versions of `bank_account_number` and `bank_routing_number` that are used to display within Chargify Admin UI, you can pass the last four digits for this fields which then will be saved in this form `XXXX[four-provided-digits]`.\n\n```json\n{\n \"payment_profile\": {\n \"customer_id\": \"24907598\",\n \"customer_vault_token\": [Existing GoCardless Customer ID]\n \"vault_token\": [Existing GoCardless Mandate ID],\n \"current_vault\": \"gocardless\",\n \"bank_name\": \"French Bank\",\n \"bank_account_number\": [Last Four Of The Existing Account Number or IBAN if applicable],\n \"bank_routing_number\": [Last Four Of The Existing Routing Number],\n \"payment_type\": \"bank_account\",\n \"billing_address\": \"20 Place de la Gare\",\n \"billing_city\": \"Colombes\",\n \"billing_state\": \"Île-de-France\",\n \"billing_zip\": \"92700\",\n \"billing_country\": \"FR\"\n }\n}\n```\n\n## SEPA Direct Debit\n\nFor more information on Stripe SEPA Direct Debit, please view the following resources:\n\n+ [Full documentation on Stripe SEPA Direct Debit](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405050826765-Stripe-SEPA-and-BECS-Direct-Debit)\n\n+ [Using Chargify.js with Stripe Direct Debit - minimal example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#minimal-example-with-sepa-or-becs-direct-debit-stripe-gateway)\n\n+ [Using Chargify.js with Stripe Direct Debit - full example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#full-example-with-sepa-direct-debit-stripe-gateway)\n\n### Stripe SEPA Direct Debit Payment Profiles\n\nThe following example creates a customer, bank account and mandate in Stripe:\n\n\n```json\n{\n \"payment_profile\": {\n \"customer_id\": \"24907598\",\n \"bank_name\": \"Deutsche bank\",\n \"bank_iban\": \"DE89370400440532013000\",\n \"payment_type\": \"bank_account\",\n \"billing_address\": \"Test\",\n \"billing_city\": \"Berlin\",\n \"billing_state\": \"Brandenburg\",\n \"billing_zip\": \"12345\",\n \"billing_country\": \"DE\"\n }\n}\n```\n\n## Stripe BECS Direct Debit\n\nFor more information on Stripe BECS Direct Debit, please view the following resources:\n\n+ [Full documentation on Stripe BECS Direct Debit](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405050826765-Stripe-SEPA-and-BECS-Direct-Debit)\n\n+ [Using Chargify.js with Stripe BECS Direct Debit - minimal example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#minimal-example-with-sepa-or-becs-direct-debit-stripe-gateway)\n\n+ [Using Chargify.js with Stripe BECS Direct Debit - full example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#full-example-with-sepa-direct-debit-stripe-gateway)\n\n### Stripe BECS Direct Debit Payment Profiles\n\nThe following example creates a customer, bank account and mandate in Stripe:\n\n\n```json\n{\n \"payment_profile\": {\n \"customer_id\": \"24907598\",\n \"bank_name\": \"Australian bank\",\n \"bank_branch_code\": \"000000\",\n \"bank_account_number\": \"000123456\"\n \"payment_type\": \"bank_account\",\n \"billing_address\": \"Test\",\n \"billing_city\": \"Stony Rise\",\n \"billing_state\": \"Tasmania\",\n \"billing_zip\": \"12345\",\n \"billing_country\": \"AU\"\n }\n}\n```\n\n## 3D Secure - Checkout\n\nIt may happen that a payment needs 3D Secure Authentication when the payment profile is created; this is referred to in our help docs as a [post-authentication flow](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405177432077#psd2-flows-pre-authentication-and-post-authentication). The server returns `422 Unprocessable Entity` in this case with the following response:\n\n```json\n{\n \"jsonapi\": {\n \"version\": \"1.0\"\n },\n \"errors\": [\n {\n \"title\": \"This card requires 3DSecure verification.\",\n \"detail\": \"This card requires 3D secure authentication. Redirect the customer to the URL from the action_link attribute to authenticate. Attach callback_url param to this URL if you want to be notified about the result of 3D Secure authentication. Attach redirect_url param to this URL if you want to redirect a customer back to your page after 3D Secure authentication. Example: https://checkout-test.chargifypay.test/3d-secure/checkout/pay_uerzhsxd5uhkbodx5jhvkg6yeu?one_time_token_id=93&callback_url=http://localhost:4000&redirect_url=https://yourpage.com will do a POST request to https://localhost:4000 after credit card is authenticated and will redirect a customer to https://yourpage.com after 3DS authentication.\",\n \"links\": {\n \"action_link\": \"https://checkout-test.chargifypay.test/3d-secure/checkout/pay_uerzhsxd5uhkbodx5jhvkg6yeu?one_time_token_id=93\"\n }\n }\n ]\n}\n```\n\nTo let the customer go through 3D Secure Authentication, they need to be redirected to the URL specified in `action_link`.\nOptionally, you can specify `callback_url` parameter in the `action_link` URL if you’d like to be notified about the result of 3D Secure Authentication. The `callback_url` will return the following information:\n\n- whether the authentication was successful (`success`)\n- the payment profile ID (`payment_profile_id`)\n\nLastly, you can also specify a `redirect_url` parameter within the `action_link` URL if you’d like to redirect a customer back to your site.\n\nIt is not possible to use `action_link` in an iframe inside a custom application. You have to redirect the customer directly to the `action_link`, then, to be notified about the result, use `redirect_url` or `callback_url`.\n\nThe final URL that you send a customer to complete 3D Secure may resemble the following, where the first half is the `action_link` and the second half contains a `redirect_url` and `callback_url`: `https://checkout-test.chargifypay.test/3d-secure/checkout/pay_uerzhsxd5uhkbodx5jhvkg6yeu?one_time_token_id=93&callback_url=http://localhost:4000&redirect_url=https://yourpage.com`\n\n### Example Redirect Flow\n\nYou may wish to redirect customers to different pages depending on whether their SCA was performed successfully. Here's an example flow to use as a reference:\n\n1. Create a payment profile via API; it requires 3DS\n2. You receive a `action_link` in the response.\n3. Use this `action_link` to, for example, connect with your internal resources or generate a session_id\n4. Include 1 of those attributes inside the `callback_url` and `redirect_url` to be aware which “session” this applies to\n5. Redirect the customer to the `action_link` with `callback_url` and `redirect_url` applied\n6. After the customer finishes 3DS authentication, we let you know the result by making a request to applied `callback_url`.\n7. After that, we redirect the customer to the `redirect_url`; at this point the result of authentication is known\n8. Optionally, you can use the applied \"msg\" param in the `redirect_url` to determine whether it was successful or not", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Payment-Profile-Request.yaml" - }, - "examples": { - "ACH": { - "value": { - "payment_profile": { - "customer_id": 123, - "bank_name": "Best Bank", - "bank_routing_number": "021000089", - "bank_account_number": "111111111111", - "bank_account_type": "checking", - "bank_account_holder_type": "business", - "payment_type": "bank_account" - } - } - }, - "Chargify.js": { - "value": { - "payment_profile": { - "customer_id": 1036, - "chargify_token": "tok_w68qcpnftyv53jk33jv6wk3w" - } - } - }, - "Card": { - "value": { - "payment_profile": { - "first_name": "Jessica", - "last_name": "Test", - "last_four": "1111", - "card_type": "visa", - "expiration_month": 10, - "expiration_year": 2018, - "customer_id": 19195410, - "current_vault": "bogus", - "vault_token": "1", - "billing_address": "123 Main St.", - "billing_city": "Boston", - "billing_state": "MA", - "billing_zip": "02120", - "billing_country": "US", - "billing_address_2": null, - "payment_type": "credit_card" - } - } - }, - "Local Bank Details": { - "value": { - "payment_profile": { - "customer_id": 123, - "bank_name": "Royal Bank of France", - "bank_account_number": "0000000", - "bank_routing_number": "0003", - "bank_branch_code": "00006", - "payment_type": "bank_account", - "billing_address": "20 Place de la Gare", - "billing_city": "Colombes", - "billing_state": "Île-de-France", - "billing_zip": "92700", - "billing_country": "FR" - } - } - }, - "IBAN": { - "value": { - "payment_profile": { - "customer_id": 24907598, - "bank_name": "French Bank", - "bank_iban": "FR1420041010050500013M02606", - "payment_type": "bank_account", - "billing_address": "20 Place de la Gare", - "billing_city": "Colombes", - "billing_state": "Île-de-France", - "billing_zip": "92700", - "billing_country": "FR" - } - } - }, - "Import Payment Profile": { - "value": { - "payment_profile": { - "customer_id": 24907598, - "customer_vault_token": "[Existing Vault Customer ID]", - "vault_token": "[Existing Vault Mandate ID]", - "current_vault": "gocardless", - "bank_name": "French Bank", - "payment_type": "bank_account", - "billing_address": "20 Place de la Gare", - "billing_city": "Colombes", - "billing_state": "Île-de-France", - "billing_zip": "92700", - "billing_country": "FR" - } - } - } - } - } - }, - "description": "When following the IBAN or the Local Bank details examples, a customer, bank account and mandate will be created in your current vault. If the customer, bank account, and mandate already exist in your vault, follow the Import example to link the payment profile into Chargify." - } - }, - "get": { - "summary": "List Payment Profiles", - "tags": [ - "Payment Profiles" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Payment-Profile-Response.yaml" - } - }, - "examples": { - "Example-1": { - "value": [ - { - "payment_profile": { - "id": 10089892, - "first_name": "Chester", - "last_name": "Tester", - "customer_id": 14543792, - "current_vault": "bogus", - "vault_token": "0011223344", - "billing_address": "456 Juniper Court", - "billing_city": "Boulder", - "billing_state": "CO", - "billing_zip": "80302", - "billing_country": "US", - "customer_vault_token": null, - "billing_address_2": "", - "bank_name": "Bank of Kansas City", - "masked_bank_routing_number": "XXXX6789", - "masked_bank_account_number": "XXXX3344", - "bank_account_type": "checking", - "bank_account_holder_type": "personal", - "payment_type": "bank_account", - "verified": true, - "site_gateway_setting_id": 1, - "gateway_handle": "handle" - } - }, - { - "payment_profile": { - "id": 10188522, - "first_name": "Frankie", - "last_name": "Tester", - "customer_id": 14543712, - "current_vault": "bogus", - "vault_token": "123456789", - "billing_address": "123 Montana Way", - "billing_city": "Los Angeles", - "billing_state": "CA", - "billing_zip": "90210", - "billing_country": "US", - "customer_vault_token": null, - "billing_address_2": "", - "bank_name": "Bank of Kansas City", - "masked_bank_routing_number": "XXXX6789", - "masked_bank_account_number": "XXXX6789", - "bank_account_type": "checking", - "bank_account_holder_type": "personal", - "payment_type": "bank_account", - "verified": true, - "site_gateway_setting_id": 1, - "gateway_handle": "handle" - } - } - ] - }, - "Example-2": { - "value": [ - { - "payment_profile": { - "id": 310812, - "first_name": "John15", - "last_name": "Doe04", - "masked_card_number": "XXXX-XXXX-XXXX-1111", - "card_type": "visa", - "expiration_month": 7, - "expiration_year": 2032, - "customer_id": 419675, - "current_vault": "bogus", - "vault_token": "1", - "billing_address": null, - "billing_city": null, - "billing_state": null, - "billing_zip": null, - "billing_country": null, - "customer_vault_token": null, - "billing_address_2": null, - "site_gateway_setting_id": null, - "payment_type": "credit_card", - "disabled": false, - "gateway_handle": null - } - } - ] - } - } - } - } - } - }, - "operationId": "listPaymentProfiles", - "description": "This method will return all of the active `payment_profiles` for a Site, or for one Customer within a site. If no payment profiles are found, this endpoint will return an empty array, not a 404.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "customer_id", - "description": "The ID of the customer for which you wish to list payment profiles" - } - ] - } - }, - "/payment_profiles/{payment_profile_id}.json": { - "parameters": [ - { - "$ref": "../components/parameters/payment-profile-id-path.yaml" - } - ], - "get": { - "summary": "Read Payment Profile", - "tags": [ - "Payment Profiles" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Payment-Profile-Response.yaml" - }, - "examples": { - "Card": { - "value": { - "payment_profile": { - "id": 10088716, - "first_name": "Test", - "last_name": "Subscription", - "masked_card_number": "XXXX-XXXX-XXXX-1", - "card_type": "bogus", - "expiration_month": 1, - "expiration_year": 2022, - "customer_id": 14543792, - "current_vault": "bogus", - "vault_token": "1", - "billing_address": "123 Montana Way", - "billing_city": "Billings", - "billing_state": "MT", - "billing_zip": "59101", - "billing_country": "US", - "customer_vault_token": null, - "billing_address_2": "", - "payment_type": "credit_card", - "site_gateway_setting_id": 1, - "gateway_handle": null - } - } - }, - "Bank Account": { - "value": { - "payment_profile": { - "id": 10089892, - "first_name": "Chester", - "last_name": "Tester", - "customer_id": 14543792, - "current_vault": "bogus", - "vault_token": "0011223344", - "billing_address": "456 Juniper Court", - "billing_city": "Boulder", - "billing_state": "CO", - "billing_zip": "80302", - "billing_country": "US", - "customer_vault_token": null, - "billing_address_2": "", - "bank_name": "Bank of Kansas City", - "masked_bank_routing_number": "XXXX6789", - "masked_bank_account_number": "XXXX3344", - "bank_account_type": "checking", - "bank_account_holder_type": "personal", - "payment_type": "bank_account", - "site_gateway_setting_id": 1, - "gateway_handle": null - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "operationId": "readPaymentProfile", - "description": "Using the GET method you can retrieve a Payment Profile identified by its unique ID.\n\nPlease note that a different JSON object will be returned if the card method on file is a bank account.\n\n### Response for Bank Account\n\nExample response for Bank Account:\n\n```\n{\n \"payment_profile\": {\n \"id\": 10089892,\n \"first_name\": \"Chester\",\n \"last_name\": \"Tester\",\n \"customer_id\": 14543792,\n \"current_vault\": \"bogus\",\n \"vault_token\": \"0011223344\",\n \"billing_address\": \"456 Juniper Court\",\n \"billing_city\": \"Boulder\",\n \"billing_state\": \"CO\",\n \"billing_zip\": \"80302\",\n \"billing_country\": \"US\",\n \"customer_vault_token\": null,\n \"billing_address_2\": \"\",\n \"bank_name\": \"Bank of Kansas City\",\n \"masked_bank_routing_number\": \"XXXX6789\",\n \"masked_bank_account_number\": \"XXXX3344\",\n \"bank_account_type\": \"checking\",\n \"bank_account_holder_type\": \"personal\",\n \"payment_type\": \"bank_account\",\n \"site_gateway_setting_id\": 1,\n \"gateway_handle\": null\n }\n}\n```" - }, - "put": { - "summary": "Update Payment Profile", - "tags": [ - "Payment Profiles" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Payment-Profile-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "payment_profile": { - "id": 10088716, - "first_name": "Test", - "last_name": "Subscription", - "masked_card_number": "XXXX-XXXX-XXXX-1", - "card_type": "bogus", - "expiration_month": 1, - "expiration_year": 2022, - "customer_id": 14543792, - "current_vault": "bogus", - "vault_token": "1", - "billing_address": "123 Montana Way", - "billing_city": "Billings", - "billing_state": "MT", - "billing_zip": "59101", - "billing_country": "US", - "customer_vault_token": null, - "billing_address_2": "", - "payment_type": "credit_card", - "site_gateway_setting_id": 1, - "gateway_handle": null - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-String-Map-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": { - "payment_profile": "can't be blank" - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updatePaymentProfile", - "description": "## Partial Card Updates\n\nIn the event that you are using the Authorize.net, Stripe, Cybersource, Forte or Braintree Blue payment gateways, you can update just the billing and contact information for a payment method. Note the lack of credit-card related data contained in the JSON payload.\n\nIn this case, the following JSON is acceptable:\n\n```\n{\n \"payment_profile\": {\n \"first_name\": \"Kelly\",\n \"last_name\": \"Test\",\n \"billing_address\": \"789 Juniper Court\",\n \"billing_city\": \"Boulder\",\n \"billing_state\": \"CO\",\n \"billing_zip\": \"80302\",\n \"billing_country\": \"US\",\n \"billing_address_2\": null\n }\n}\n```\n\nThe result will be that you have updated the billing information for the card, yet retained the original card number data.\n\n## Specific notes on updating payment profiles\n\n- Merchants with **Authorize.net**, **Cybersource**, **Forte**, **Braintree Blue** or **Stripe** as their payment gateway can update their Customer’s credit cards without passing in the full credit card number and CVV.\n\n- If you are using **Authorize.net**, **Cybersource**, **Forte**, **Braintree Blue** or **Stripe**, Chargify will ignore the credit card number and CVV when processing an update via the API, and attempt a partial update instead. If you wish to change the card number on a payment profile, you will need to create a new payment profile for the given customer.\n\n- A Payment Profile cannot be updated with the attributes of another type of Payment Profile. For example, if the payment profile you are attempting to update is a credit card, you cannot pass in bank account attributes (like `bank_account_number`), and vice versa.\n\n- Updating a payment profile directly will not trigger an attempt to capture a past-due balance. If this is the intent, update the card details via the Subscription instead.\n\n- If you are using Authorize.net or Stripe, you may elect to manually trigger a retry for a past due subscription after a partial update.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Payment-Profile-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "payment_profile": { - "first_name": "Graham", - "last_name": "Test", - "full_number": "4111111111111111", - "card_type": "master", - "expiration_month": "04", - "expiration_year": "2030", - "current_vault": "bogus", - "billing_address": "456 Juniper Court", - "billing_city": "Boulder", - "billing_state": "CO", - "billing_zip": "80302", - "billing_country": "US", - "billing_address_2": null - } - } - } - } - } - } - } - }, - "delete": { - "summary": "Delete Unused Payment Profile", - "tags": [ - "Payment Profiles" - ], - "responses": { - "204": { - "description": "No Content" - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "The payment profile is in use by one or more subscriptions and cannot be deleted" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "deleteUnusedPaymentProfile", - "description": "Deletes an unused payment profile.\n\nIf the payment profile is in use by one or more subscriptions or groups, a 422 and error message will be returned." - } - }, - "/subscriptions/{subscription_id}/payment_profiles/{payment_profile_id}.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - }, - { - "$ref": "../components/parameters/payment-profile-id-path.yaml" - } - ], - "delete": { - "summary": "Delete Subscription Payment Profile", - "responses": { - "204": { - "description": "No Content" - } - }, - "operationId": "deleteSubscriptionsPaymentProfile", - "description": "This will delete a payment profile belonging to the customer on the subscription.\n\n+ If the customer has multiple subscriptions, the payment profile will be removed from all of them.\n\n+ If you delete the default payment profile for a subscription, you will need to specify another payment profile to be the default through the api, or either prompt the user to enter a card in the billing portal or on the self-service page, or visit the Payment Details tab on the subscription in the Admin UI and use the “Add New Credit Card” or “Make Active Payment Method” link, (depending on whether there are other cards present).", - "tags": [ - "Payment Profiles" - ] - } - }, - "/bank_accounts/{bank_account_id}/verification.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "bank_account_id", - "description": "Identifier of the bank account in the system.", - "in": "path", - "required": true - } - ], - "put": { - "summary": "Verify Bank Account", - "tags": [ - "Payment Profiles" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Bank-Account-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "payment_profile": { - "id": 10089892, - "first_name": "Chester", - "last_name": "Tester", - "customer_id": 14543792, - "current_vault": "stripe_connect", - "vault_token": "cus_0123abc456def", - "billing_address": "456 Juniper Court", - "billing_city": "Boulder", - "billing_state": "CO", - "billing_zip": "80302", - "billing_country": "US", - "customer_vault_token": null, - "billing_address_2": "", - "bank_name": "Bank of Kansas City", - "masked_bank_routing_number": "XXXX6789", - "masked_bank_account_number": "XXXX3344", - "bank_account_type": "checking", - "bank_account_holder_type": "personal", - "payment_type": "bank_account" - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "You have tried to verify this bank account 10 times. To continue trying to verify the account, please reach out to us directly." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "verifyBankAccount", - "description": "Submit the two small deposit amounts the customer received in their bank account in order to verify the bank account. (Stripe only)", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Bank-Account-Verification-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "bank_account_verification": { - "deposit_1_in_cents": 32, - "deposit_2_in_cents": 45 - } - } - } - } - } - } - } - } - }, - "/invoices/{uid}/refunds.json": { - "parameters": [ - { - "$ref": "../components/parameters/invoice-uid-path.yaml" - } - ], - "post": { - "summary": "Refund Invoice", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Invoice.yaml" - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Amount: must be greater than 0." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "refundInvoice", - "description": "Refund an invoice, segment, or consolidated invoice.\n\n## Partial Refund for Consolidated Invoice\n\nA refund less than the total of a consolidated invoice will be split across its segments.\n\nA $50.00 refund on a $100.00 consolidated invoice with one $60.00 and one $40.00 segment, the refunded amount will be applied as 50% of each ($30.00 and $20.00 respectively).", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Refund-Invoice-Request.yaml" - }, - "examples": { - "Refund Invoice": { - "value": { - "refund": { - "amount": "100.00", - "memo": "Refund for Basic Plan renewal", - "payment_id": 12345, - "external": false, - "apply_credit": false, - "void_invoice": true - } - } - }, - "Refund Consolidated Invoice": { - "value": { - "refund": { - "memo": "Refund for basic plan renewal", - "payment_id": 101, - "amount": "125.00", - "segment_uids": [ - "inv_123", - "inv_789" - ] - } - } - }, - "Refund All Segments of Consolidated Invoice": { - "value": { - "refund": { - "memo": "Refund for basic plan renewal", - "payment_id": 10101, - "segment_uids": "all" - } - } - } - } - } - } - } - } - }, - "/invoices.json": { - "get": { - "summary": "List Invoices", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Invoices-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "invoices": [ - { - "uid": "inv_8htcd29wcq3q6", - "site_id": 51288, - "customer_id": 20153415, - "subscription_id": 23277588, - "number": "125", - "sequence_number": 125, - "issue_date": "2018-09-20", - "due_date": "2018-09-20", - "paid_date": "2018-09-20", - "status": "paid", - "collection_method": "automatic", - "payment_instructions": "Make checks payable to Acme, Inc.", - "currency": "USD", - "consolidation_level": "parent", - "parent_invoice_uid": null, - "parent_invoice_number": null, - "group_primary_subscription_id": 23277588, - "product_name": "Trial and setup fee", - "product_family_name": "Billing Plans", - "seller": { - "name": "General Goods", - "address": { - "street": "123 General Goods Way", - "line2": "Apt. 10", - "city": "Boston", - "state": "MA", - "zip": "02120", - "country": "US" - }, - "phone": "555-555-1212" - }, - "customer": { - "chargify_id": 20153415, - "first_name": "Meg", - "last_name": "Example", - "organization": "", - "email": "meg@example.com" - }, - "memo": "Please pay within 15 days.", - "billing_address": { - "street": "123 I Love Cats Way", - "line2": "", - "city": "Boston", - "state": "MA", - "zip": "90210", - "country": "US" - }, - "shipping_address": { - "street": "123 I Love Cats Way", - "line2": "", - "city": "Boston", - "state": "MA", - "zip": "90210", - "country": "US" - }, - "subtotal_amount": "100.0", - "discount_amount": "0.0", - "tax_amount": "0.0", - "total_amount": "100.0", - "credit_amount": "0.0", - "paid_amount": "100.0", - "refund_amount": "0.0", - "due_amount": "0.0", - "public_url": "https://www.chargifypay.com/invoice/inv_8htcd29wcq3q6?token=n9fr5fxff5v74c7h9srg3cwd" - }, - { - "uid": "inv_8hr3546xp4h8n", - "site_id": 51288, - "customer_id": 21687686, - "subscription_id": 22007644, - "number": "124", - "sequence_number": 124, - "issue_date": "2018-09-18", - "due_date": "2018-09-18", - "paid_date": null, - "status": "open", - "collection_method": "remittance", - "payment_instructions": "Make checks payable to Acme, Inc.", - "currency": "USD", - "consolidation_level": "none", - "parent_invoice_uid": null, - "parent_invoice_number": null, - "group_primary_subscription_id": null, - "product_name": "Trial and setup fee", - "product_family_name": "Billing Plans", - "seller": { - "name": "General Goods", - "address": { - "street": "123 General Goods Way", - "line2": "Apt. 10", - "city": "Boston", - "state": "MA", - "zip": "02120", - "country": "US" - }, - "phone": "555-555-1212" - }, - "customer": { - "chargify_id": 21687686, - "first_name": "Charlene", - "last_name": "Tester", - "organization": "", - "email": "food@example.com" - }, - "memo": "Please pay within 15 days.", - "billing_address": { - "street": "", - "line2": "", - "city": "", - "state": "", - "zip": "", - "country": "" - }, - "shipping_address": { - "street": "", - "line2": "", - "city": "", - "state": "", - "zip": "", - "country": "" - }, - "subtotal_amount": "100.0", - "discount_amount": "0.0", - "tax_amount": "0.0", - "total_amount": "100.0", - "credit_amount": "0.0", - "paid_amount": "0.0", - "refund_amount": "0.0", - "due_amount": "100.0", - "public_url": "https://www.chargifypay.com/invoice/inv_8hr3546xp4h8n?token=n9fr5fxff5v74c7h9srg3cwd" - }, - { - "uid": "inv_8hr3546wdwxkr", - "site_id": 51288, - "customer_id": 21687670, - "subscription_id": 22007627, - "number": "123", - "sequence_number": 123, - "issue_date": "2018-09-18", - "due_date": "2018-09-18", - "paid_date": "2018-09-18", - "status": "paid", - "collection_method": "automatic", - "payment_instructions": "Make checks payable to Acme, Inc.", - "currency": "USD", - "consolidation_level": "none", - "parent_invoice_uid": null, - "parent_invoice_number": null, - "group_primary_subscription_id": null, - "product_name": "Trial End - Free", - "product_family_name": "Billing Plans", - "seller": { - "name": "General Goods", - "address": { - "street": "123 General Goods Way", - "line2": "Apt. 10", - "city": "Boston", - "state": "MA", - "zip": "02120", - "country": "US" - }, - "phone": "555-555-1212" - }, - "customer": { - "chargify_id": 21687670, - "first_name": "Hello", - "last_name": "World", - "organization": "123", - "email": "example@example.com" - }, - "memo": "Please pay within 15 days.", - "billing_address": { - "street": "123 Anywhere Street", - "line2": "", - "city": "Boston", - "state": "MA", - "zip": "02120", - "country": "US" - }, - "shipping_address": { - "street": "", - "line2": "", - "city": "Boston", - "state": "AL", - "zip": "02120", - "country": "US" - }, - "subtotal_amount": "0.0", - "discount_amount": "0.0", - "tax_amount": "0.0", - "total_amount": "0.0", - "credit_amount": "0.0", - "paid_amount": "0.0", - "refund_amount": "0.0", - "due_amount": "0.0", - "public_url": "https://www.chargifypay.com/invoice/inv_8hr3546wdwxkr?token=n9fr5fxff5v74c7h9srg3cwd" - }, - { - "uid": "inv_8hjtk8bz56bbp", - "site_id": 51288, - "customer_id": 20137757, - "subscription_id": 20541100, - "number": "122", - "sequence_number": 122, - "issue_date": "2018-09-10", - "due_date": "2018-09-10", - "paid_date": "2018-09-10", - "status": "paid", - "collection_method": "automatic", - "payment_instructions": "Make checks payable to Acme, Inc.", - "currency": "USD", - "consolidation_level": "none", - "parent_invoice_uid": null, - "parent_invoice_number": null, - "group_primary_subscription_id": null, - "product_name": "$0 Product", - "product_family_name": "Billing Plans", - "seller": { - "name": "General Goods", - "address": { - "street": "123 General Goods Way", - "line2": "Apt. 10", - "city": "Boston", - "state": "MA", - "zip": "02120", - "country": "US" - }, - "phone": "555-555-1212" - }, - "customer": { - "chargify_id": 20137757, - "first_name": "Sasha", - "last_name": "Example", - "organization": "", - "email": "example@example.com" - }, - "memo": "Please pay within 15 days.", - "billing_address": { - "street": "123 I Love Cats Way", - "line2": "", - "city": "Catville", - "state": "MA", - "zip": "90210", - "country": "US" - }, - "shipping_address": { - "street": "123 I Love Cats Way", - "line2": "", - "city": "Catville", - "state": "AL", - "zip": "90210", - "country": "US" - }, - "subtotal_amount": "0.0", - "discount_amount": "0.0", - "tax_amount": "0.0", - "total_amount": "0.0", - "credit_amount": "0.0", - "paid_amount": "0.0", - "refund_amount": "0.0", - "due_amount": "0.0", - "public_url": "https://www.chargifypay.com/invoice/inv_8hjtk8bz56bbp?token=fb6kpjz5rcr2vttyjs4rcv6y" - } - ] - } - } - } - } - } - } - }, - "operationId": "listInvoices", - "description": "By default, invoices returned on the index will only include totals, not detailed breakdowns for `line_items`, `discounts`, `taxes`, `credits`, `payments`, `custom_fields`, or `refunds`. To include breakdowns, pass the specific field as a key in the query with a value set to `true`.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_date", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns invoices with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_date", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns invoices with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified." - }, - { - "schema": { - "$ref": "../components/schemas/Invoice-Status.yaml" - }, - "in": "query", - "name": "status", - "description": "The current status of the invoice. Allowed Values: draft, open, paid, pending, voided" - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "subscription_id", - "description": "The subscription's ID." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "subscription_group_uid", - "description": "The UID of the subscription group you want to fetch consolidated invoices for. This will return a paginated list of consolidated invoices for the specified group." - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "string", - "default": "desc", - "enum": [ - "asc", - "desc" - ] - }, - "in": "query", - "name": "direction", - "description": "The sort direction of the returned invoices." - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "line_items", - "description": "Include line items data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "discounts", - "description": "Include discounts data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "taxes", - "description": "Include taxes data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "credits", - "description": "Include credits data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "payments", - "description": "Include payments data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "custom_fields", - "description": "Include custom fields data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "refunds", - "description": "Include refunds data" - }, - { - "schema": { - "$ref": "../components/schemas/Invoice-Date-Field.yaml" - }, - "in": "query", - "name": "date_field", - "description": "The type of filter you would like to apply to your search. Use in query `date_field=issue_date`." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_datetime", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns invoices with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. Allowed to be used only along with date_field set to created_at or updated_at." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_datetime", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns invoices with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. Allowed to be used only along with date_field set to created_at or updated_at." - }, - { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [ - 1, - 2, - 3 - ] - }, - "in": "query", - "name": "customer_ids", - "style": "form", - "explode": false, - "description": "Allows fetching invoices with matching customer id based on provided values. Use in query `customer_ids=1,2,3`." - }, - { - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "1234", - "1235" - ] - }, - "in": "query", - "name": "number", - "style": "form", - "explode": false, - "description": "Allows fetching invoices with matching invoice number based on provided values. Use in query `number=1234,1235`." - }, - { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [ - 23, - 34 - ] - }, - "in": "query", - "name": "product_ids", - "style": "form", - "explode": false, - "description": "Allows fetching invoices with matching line items product ids based on provided values. Use in query `product_ids=23,34`." - }, - { - "schema": { - "$ref": "../components/schemas/Invoice-Sort-Field.yaml" - }, - "in": "query", - "name": "sort", - "description": "Allows specification of the order of the returned list. Use in query `sort=total_amount`." - } - ] - } - }, - "/invoices/{uid}.json": { - "parameters": [ - { - "$ref": "../components/parameters/invoice-uid-path.yaml" - } - ], - "get": { - "summary": "Read Invoice", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Invoice.yaml" - }, - "examples": { - "Example": { - "value": { - "uid": "inv_8gd8tdhtd3hgr", - "site_id": 51288, - "customer_id": 20194505, - "subscription_id": 20597774, - "number": "117", - "sequence_number": 117, - "issue_date": "2018-07-26", - "due_date": "2018-07-26", - "paid_date": "2018-07-26", - "status": "paid", - "collection_method": "automatic", - "payment_instructions": "Make checks payable to Acme, Inc.", - "currency": "USD", - "consolidation_level": "none", - "parent_invoice_uid": null, - "parent_invoice_number": null, - "group_primary_subscription_id": null, - "product_name": "Monthly Product", - "product_family_name": "Billing Plans", - "seller": { - "name": "General Goods", - "address": { - "street": "123 General Goods Way", - "line2": "Apt. 10", - "city": "Boston", - "state": "MA", - "zip": "02120", - "country": "US" - }, - "phone": "555-555-1212" - }, - "customer": { - "chargify_id": 20194505, - "first_name": "Joe", - "last_name": "Example", - "organization": null, - "email": "joe@example.com" - }, - "memo": "Please pay within 15 days.", - "billing_address": { - "street": null, - "line2": null, - "city": null, - "state": null, - "zip": null, - "country": null - }, - "shipping_address": { - "street": null, - "line2": null, - "city": null, - "state": null, - "zip": null, - "country": null - }, - "subtotal_amount": "100.0", - "discount_amount": "0.0", - "tax_amount": "0.0", - "total_amount": "100.0", - "credit_amount": "0.0", - "paid_amount": "100.0", - "refund_amount": "0.0", - "due_amount": "0.0", - "line_items": [ - { - "uid": "li_8gd8tdhhgk55k", - "title": "Monthly Product", - "description": "Jul 26, 2018 - Aug 26, 2018", - "quantity": "1.0", - "unit_price": "100.0", - "subtotal_amount": "100.0", - "discount_amount": "0.0", - "tax_amount": "0.0", - "total_amount": "100.0", - "tiered_unit_price": false, - "period_range_start": "2018-07-26", - "period_range_end": "2018-08-26", - "product_id": 4607632, - "product_version": 1, - "component_id": null, - "price_point_id": null - } - ], - "discounts": [], - "taxes": [], - "credits": [], - "payments": [ - { - "transaction_time": "2018-07-26T15:22:02Z", - "memo": "Joe Example - Monthly Product: Renewal payment", - "original_amount": "100.0", - "applied_amount": "100.0", - "payment_method": { - "card_brand": "bogus", - "card_expiration": "10/2020", - "last_four": null, - "masked_card_number": "XXXX-XXXX-XXXX-1", - "type": "credit_card" - }, - "transaction_id": 253028955, - "prepayment": false - } - ], - "refunds": [], - "custom_fields": [], - "public_url": "https://www.chargifypay.com/invoice/inv_8jzrw74xq8kxr?token=fb6kpjz5rcr2vttyjs4rcv6y" - } - } - } - } - } - } - }, - "operationId": "readInvoice", - "description": "Use this endpoint to retrieve the details for an invoice." - } - }, - "/invoices/events.json": { - "get": { - "summary": "List Invoice Events", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Invoice-Events-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "events": [ - { - "id": 83, - "event_type": "apply_payment", - "event_data": { - "memo": "Non-Resumable Canceled On Purpose - Standard Plan: Renewal payment", - "original_amount": "168.61", - "applied_amount": "168.61", - "transaction_time": "2018-08-01T16:00:00Z", - "payment_method": { - "card_brand": "visa", - "card_expiration": "12/2022", - "last_four": null, - "masked_card_number": "XXXX-XXXX-XXXX-1111", - "type": "credit_card" - }, - "consolidation_level": "none" - }, - "timestamp": "2018-08-01T16:00:00Z", - "invoice": { - "id": 614942008934401500, - "uid": "inv_8gk5bwkct3gqt", - "site_id": 20, - "customer_id": 6, - "subscription_id": 10, - "number": "25", - "sequence_number": 25, - "transaction_time": "2018-08-01T16:00:00Z", - "created_at": "2018-08-01T16:00:00Z", - "updated_at": "2018-08-01T16:00:00Z", - "issue_date": "2018-08-01", - "due_date": "2018-08-01", - "paid_date": "2018-08-01", - "status": "paid", - "role": "renewal", - "collection_method": "automatic", - "payment_instructions": "Please make checks payable to \"Acme, Inc.\"", - "currency": "USD", - "consolidation_level": "none", - "parent_invoice_id": null, - "subscription_group_id": null, - "parent_invoice_number": null, - "product_name": "Standard Plan", - "product_family_name": "Cloud Compute Servers", - "seller": { - "name": "Acme, Inc.", - "address": { - "street": null, - "line2": null, - "city": null, - "state": null, - "zip": null, - "country": null - }, - "phone": "555-555-1234 x137", - "logo_url": null - }, - "customer": { - "chargify_id": 6, - "first_name": "Non-Resumable", - "last_name": "Canceled On Purpose", - "organization": null, - "email": "evan4@example.com" - }, - "payer": { - "chargify_id": 6, - "first_name": "Non-Resumable", - "last_name": "Canceled On Purpose", - "organization": null, - "email": "evan4@example.com" - }, - "recipient_emails": [], - "net_terms": 0, - "memo": "Thanks for your business! If you have any questions, please contact your account manager.", - "billing_address": { - "street": "200 Billing Rd.", - "line2": "Suite 100", - "city": "Needham", - "state": "MA", - "zip": "02494", - "country": "US" - }, - "shipping_address": { - "street": "100 Shipping St.", - "line2": "Apt 200", - "city": "Pleasantville", - "state": "NC", - "zip": "12345", - "country": "US" - }, - "line_items": [ - { - "uid": "li_8gk5bwkct3gqk", - "title": "Standard Plan", - "description": "08/01/2018 - 09/01/2018", - "quantity": "1.0", - "unit_price": "99.0", - "subtotal_amount": "99.0", - "discount_amount": "9.9", - "tax_amount": "6.01425", - "total_amount": "95.11425", - "tiered_unit_price": false, - "period_range_start": "2018-08-01", - "period_range_end": "2018-09-01", - "transaction_id": 120, - "product_id": 84, - "product_version": 1, - "component_id": null, - "price_point_id": null, - "hide": false - }, - { - "uid": "li_8gk5bwkct3gqm", - "title": "Small Instance (Hourly)", - "description": "07/22/2018 - 08/01/2018", - "quantity": "162.0", - "unit_price": "0.09567901", - "subtotal_amount": "15.5", - "discount_amount": "1.55", - "tax_amount": "0.941625", - "total_amount": "14.891625", - "tiered_unit_price": true, - "period_range_start": "2018-07-22", - "period_range_end": "2018-08-01", - "transaction_id": 121, - "product_id": 84, - "product_version": 1, - "component_id": 76, - "price_point_id": null, - "hide": false, - "component_cost_data": { - "rates": [ - { - "component_code_id": null, - "price_point_id": 160, - "product_id": 84, - "quantity": "162.0", - "amount": "15.5", - "pricing_scheme": "tiered", - "tiers": [ - { - "starting_quantity": 1, - "ending_quantity": 100, - "quantity": "100.0", - "unit_price": "0.0", - "amount": "0.0" - }, - { - "starting_quantity": 101, - "ending_quantity": null, - "quantity": "62.0", - "unit_price": "0.25", - "amount": "15.5" - } - ] - } - ] - } - }, - { - "uid": "li_8gk5bwkct3gqn", - "title": "Large Instance (Hourly)", - "description": "07/22/2018 - 08/01/2018", - "quantity": "194.0", - "unit_price": "0.24226804", - "subtotal_amount": "47.0", - "discount_amount": "4.7", - "tax_amount": "2.85525", - "total_amount": "45.15525", - "tiered_unit_price": true, - "period_range_start": "2018-07-22", - "period_range_end": "2018-08-01", - "transaction_id": 122, - "product_id": 84, - "product_version": 1, - "component_id": 77, - "price_point_id": null, - "hide": false, - "component_cost_data": { - "rates": [ - { - "component_code_id": null, - "price_point_id": 161, - "product_id": 84, - "quantity": "194.0", - "amount": "47.0", - "pricing_scheme": "tiered", - "tiers": [ - { - "starting_quantity": 1, - "ending_quantity": 100, - "quantity": "100.0", - "unit_price": "0.0", - "amount": "0.0" - }, - { - "starting_quantity": 101, - "ending_quantity": null, - "quantity": "94.0", - "unit_price": "0.5", - "amount": "47.0" - } - ] - } - ] - } - }, - { - "uid": "li_8gk5bwkct3gqp", - "title": "IP Addresses", - "description": "08/01/2018 - 09/01/2018", - "quantity": "7.0", - "unit_price": "2.0", - "subtotal_amount": "14.0", - "discount_amount": "1.4", - "tax_amount": "0.8505", - "total_amount": "13.4505", - "tiered_unit_price": false, - "period_range_start": "2018-08-01", - "period_range_end": "2018-09-01", - "transaction_id": 123, - "product_id": 84, - "product_version": 1, - "component_id": 79, - "price_point_id": 163, - "hide": false, - "component_cost_data": { - "rates": [ - { - "component_code_id": null, - "price_point_id": 163, - "product_id": 84, - "quantity": "7.0", - "amount": "14.0", - "pricing_scheme": "per_unit", - "tiers": [ - { - "starting_quantity": 1, - "ending_quantity": null, - "quantity": "7.0", - "unit_price": "2.0", - "amount": "14.0" - } - ] - } - ] - } - } - ], - "subtotal_amount": "175.5", - "discount_amount": "17.55", - "discounts": [ - { - "uid": "dli_8gk5bwkct3gqq", - "title": "Multi-service discount (10%)", - "description": null, - "code": "MULTI3", - "source_type": "Coupon", - "source_id": 40, - "discount_type": "percentage", - "percentage": "10.0", - "eligible_amount": "175.5", - "discount_amount": "17.55", - "transaction_id": 124, - "line_item_breakouts": [ - { - "uid": "li_8gk5bwkct3gqk", - "eligible_amount": "99.0", - "discount_amount": "9.9" - }, - { - "uid": "li_8gk5bwkct3gqm", - "eligible_amount": "15.5", - "discount_amount": "1.55" - }, - { - "uid": "li_8gk5bwkct3gqn", - "eligible_amount": "47.0", - "discount_amount": "4.7" - }, - { - "uid": "li_8gk5bwkct3gqp", - "eligible_amount": "14.0", - "discount_amount": "1.4" - } - ] - } - ], - "tax_amount": "10.66", - "taxes": [ - { - "uid": "tli_8gk5bwkct3gqr", - "title": "NC Sales Tax", - "description": null, - "source_type": "Tax", - "source_id": 1, - "percentage": "6.75", - "taxable_amount": "157.95", - "tax_amount": "10.66", - "transaction_id": 125, - "line_item_breakouts": [ - { - "uid": "li_8gk5bwkct3gqk", - "taxable_amount": "89.1", - "tax_amount": "6.01425" - }, - { - "uid": "li_8gk5bwkct3gqm", - "taxable_amount": "13.95", - "tax_amount": "0.941625" - }, - { - "uid": "li_8gk5bwkct3gqn", - "taxable_amount": "42.3", - "tax_amount": "2.85525" - }, - { - "uid": "li_8gk5bwkct3gqp", - "taxable_amount": "12.6", - "tax_amount": "0.8505" - } - ], - "tax_component_breakouts": [ - { - "tax_rule_id": 1, - "percentage": "6.75", - "country_code": "US", - "subdivision_code": "NC" - } - ] - } - ], - "credit_amount": "0.0", - "refund_amount": "0.0", - "total_amount": "168.61", - "paid_amount": "168.61", - "due_amount": "0.0", - "credits": [], - "refunds": [], - "payments": [ - { - "memo": "Non-Resumable Canceled On Purpose - Standard Plan: Renewal payment", - "original_amount": "168.61", - "applied_amount": "168.61", - "transaction_time": "2018-08-01T16:00:00Z", - "payment_method": { - "card_brand": "visa", - "card_expiration": "12/2022", - "last_four": null, - "masked_card_number": "XXXX-XXXX-XXXX-1111", - "type": "credit_card" - }, - "transaction_id": 126, - "prepayment": false - } - ], - "custom_fields": [], - "display_settings": { - "hide_zero_subtotal_lines": false, - "include_discounts_on_lines": false - } - } - } - ], - "page": 48, - "per_page": 1, - "total_pages": 102 - } - } - } - } - } - } - }, - "operationId": "listInvoiceEvents", - "description": "This endpoint returns a list of invoice events. Each event contains event \"data\" (such as an applied payment) as well as a snapshot of the `invoice` at the time of event completion.\n\nExposed event types are:\n\n+ issue_invoice\n+ apply_credit_note\n+ apply_payment\n+ refund_invoice\n+ void_invoice\n+ void_remainder\n+ backport_invoice\n+ change_invoice_status\n+ change_invoice_collection_method\n+ remove_payment\n+ failed_payment\n+ apply_debit_note\n+ create_debit_note\n+ change_chargeback_status\n\nInvoice events are returned in ascending order.\n\nIf both a `since_date` and `since_id` are provided in request parameters, the `since_date` will be used.\n\nNote - invoice events that occurred prior to 09/05/2018 __will not__ contain an `invoice` snapshot.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "since_date", - "description": "The timestamp in a format `YYYY-MM-DD T HH:MM:SS Z`, or `YYYY-MM-DD`(in this case, it returns data from the beginning of the day). of the event from which you want to start the search. All the events before the `since_date` timestamp are not returned in the response." - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "since_id", - "description": "The ID of the event from which you want to start the search(ID is not included. e.g. if ID is set to 2, then all events with ID 3 and more will be shown) This parameter is not used if since_date is defined." - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "schema": { - "type": "integer", - "default": 100, - "min": 1, - "max": 200 - }, - "in": "query", - "name": "per_page", - "description": "This parameter indicates how many records to fetch in each request. Default value is 100. The maximum allowed values is 200; any per_page value over 200 will be changed to 200." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "invoice_uid", - "description": "Providing an invoice_uid allows for scoping of the invoice events to a single invoice or credit note." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "description": "Use this parameter if you want to fetch also invoice events with change_invoice_status type.", - "name": "with_change_invoice_status" - }, - { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Invoice-Event-Type.yaml" - } - }, - "in": "query", - "name": "event_types", - "style": "form", - "explode": false, - "description": "Filter results by event_type. Supply a comma separated list of event types (listed above). Use in query: `event_types=void_invoice,void_remainder`." - } - ] - } - }, - "/invoices/{uid}/payments.json": { - "parameters": [ - { - "$ref": "../components/parameters/invoice-uid-path.yaml" - } - ], - "post": { - "summary": "Record Payment for Invoice", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Invoice.yaml" - } - } - } - }, - "422": { - "description": "Unprocessable Entity", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "errors": [ - "Amount: is not a number." - ] - } - }, - "Example-2": { - "value": { - "errors": [ - "Payment amount 10.50 exceeds due amount 4.00" - ] - } - }, - "Example-3": { - "value": { - "errors": [ - "Invoice must be open or in collections to apply payment" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "recordPaymentForInvoice", - "description": "This API call should be used when you want to record a payment of a given type against a specific invoice. If you would like to apply a payment across multiple invoices, you can use the Bulk Payment endpoint.\n\n## Create a Payment from the existing payment profile\n\nIn order to apply a payment to an invoice using an existing payment profile, specify `type` as `payment`, the amount less than the invoice total, and the customer's `payment_profile_id`. The ID of a payment profile might be retrieved via the Payment Profiles API endpoint.\n\n```\n{\n \"type\": \"payment\",\n \"payment\": {\n \"amount\": 10.00,\n \"payment_profile_id\": 123\n }\n}\n```\n\n## Create a Payment from the Subscription's Prepayment Account\n\nIn order apply a prepayment to an invoice, specify the `type` as `prepayment`, and also the `amount`.\n\n```\n{\n \"type\": \"prepayment\",\n \"payment\": {\n \"amount\": 10.00\n }\n}\n```\n\nNote that the `amount` must be less than or equal to the Subscription's Prepayment account balance.\n\n## Create a Payment from the Subscription's Service Credit Account\n\nIn order to apply a service credit to an invoice, specify the `type` as `service_credit`, and also the `amount`:\n\n\n```\n{\n \"type\": \"service_credit\",\n \"payment\": {\n \"amount\": 10.00\n }\n}\n```\n\nNote that Chargify will attempt to fully pay the invoice's `due_amount` from the Subscription's Service Credit account. At this time, partial payments from a Service Credit Account are only allowed for consolidated invoices (subscription groups). Therefore, for normal invoices the Service Credit account balance must be greater than or equal to the invoice's `due_amount`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Invoice-Payment-Request.yaml" - }, - "examples": { - "Example 1": { - "value": { - "payment": { - "amount": 124.33, - "memo": "for John Smith", - "method": "check", - "details": "#0102" - } - } - }, - "Example 2": { - "value": { - "type": "prepayment", - "payment": { - "amount": 10 - } - } - } - } - } - }, - "description": "" - } - } - }, - "/invoices/payments.json": { - "post": { - "summary": "Record Payment for Multiple Invoices", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Multi-Invoice-Payment-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "payment": { - "transaction_id": 1, - "total_amount": "100.00", - "currency_code": "USD", - "applications": [ - { - "invoice_uid": "inv_8gk5bwkct3gqt", - "application_uid": "pmt_1tr0hgsct3ybx", - "applied_amount": "50.00" - }, - { - "invoice_uid": "inv_7bc6bwkct3lyt", - "application_uid": "pmt_2", - "applied_amount": "50.00" - } - ] - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Total amount must be greater than 0", - "Total amount must be higher or equal to invoices payment amount sum", - "Invoice does not exist", - "Payment method must valid", - "Invoices must be in the same currency", - "A required parameter is missing", - "Invoices belong to different subscriptions. Only invoices from same subscriptions are allowed when total amount exceeds invoices due amount.", - "Individual invoices may not be overpaid. To create a prepayment, add overage to the total amount.", - "Paying consolidated invoices is forbidden", - "Invoice payment amounts must be greater than 0", - "Invoice must have an open balance", - "Effective date is missing", - "Effective date is invalid or malformed", - "Effective date must occur in the past", - "Multiple applications associated to a single invoice, please aggregate and send as a single application per invoice." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "recordPaymentForMultipleInvoices", - "description": "This API call should be used when you want to record an external payment against multiple invoices.\n\n In order apply a payment to multiple invoices, at minimum, specify the `amount` and `applications` (i.e., `invoice_uid` and `amount`) details.\n\n```\n{\n \"payment\": {\n \"memo\": \"to pay the bills\",\n \"details\": \"check number 8675309\",\n \"method\": \"check\",\n \"amount\": \"250.00\",\n \"applications\": [\n {\n \"invoice_uid\": \"inv_8gk5bwkct3gqt\",\n \"amount\": \"100.00\"\n },\n {\n \"invoice_uid\": \"inv_7bc6bwkct3lyt\",\n \"amount\": \"150.00\"\n }\n ]\n }\n}\n```\n\nNote that the invoice payment amounts must be greater than 0. Total amount must be greater or equal to invoices payment amount sum.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Multi-Invoice-Payment-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "payment": { - "memo": "to pay the bills", - "details": "check number 8675309", - "method": "check", - "amount": "100.00", - "applications": [ - { - "invoice_uid": "inv_8gk5bwkct3gqt", - "amount": "50.00" - }, - { - "invoice_uid": "inv_7bc6bwkct3lyt", - "amount": "50.00" - } - ] - } - } - } - } - } - } - }, - "parameters": [] - }, - "parameters": [] - }, - "/credit_notes.json": { - "get": { - "summary": "List Credit Notes", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Credit-Notes-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "credit_notes": [ - { - "uid": "cn_8m9vbd5kkv7kr", - "site_id": 20, - "customer_id": 3, - "subscription_id": 2, - "number": "77", - "sequence_number": 78, - "issue_date": "2018-12-31", - "applied_date": "2018-12-31", - "status": "applied", - "currency": "USD", - "memo": "Refund for overpayment", - "seller": { - "name": "Acme, Inc.", - "address": { - "street": "122 E Houston St", - "line2": "Suite 105", - "city": "San Antonio", - "state": "TX", - "zip": "78205", - "country": "US" - }, - "phone": "555-555-1234 x137" - }, - "customer": { - "chargify_id": 3, - "first_name": "Marty", - "last_name": "McFly", - "organization": "Time Travellers, Inc.", - "email": "timetraveller1985@example.com", - "reference": null - }, - "billing_address": { - "street": "200 Billing Rd.", - "line2": "Suite 100", - "city": "Needham", - "state": "MA", - "zip": "02494", - "country": "US" - }, - "shipping_address": { - "street": "100 Shipping St.", - "line2": "Apt 200", - "city": "Pleasantville", - "state": "NC", - "zip": "12345", - "country": "US" - }, - "subtotal_amount": "208.69341779", - "discount_amount": "20.87125167", - "tax_amount": "12.67783387", - "total_amount": "200.5", - "applied_amount": "200.5", - "remaining_amount": "0.0", - "line_items": [ - { - "uid": "cnli_8k5jvdzct4h9x", - "title": "IP Addresses: 5 to 10 addresses", - "description": "38.2% credit", - "quantity": "0.9855", - "unit_price": "2.0", - "subtotal_amount": "1.971004", - "discount_amount": "0.19862831", - "tax_amount": "0.11963536", - "total_amount": "1.89201105", - "tiered_unit_price": false, - "period_range_start": "2018-11-30", - "period_range_end": "2018-11-30", - "product_id": 85, - "product_version": 1, - "component_id": 81, - "price_point_id": 165 - }, - { - "uid": "cnli_8kjttvjcjx8b4", - "title": "Professional Plan", - "description": "38.2% credit", - "quantity": "0.382", - "unit_price": "299.0", - "subtotal_amount": "114.21127834", - "discount_amount": "11.42112783", - "tax_amount": "6.93833516", - "total_amount": "109.72848567", - "tiered_unit_price": false, - "period_range_start": "2018-12-30", - "period_range_end": "2018-12-30", - "product_id": 85, - "product_version": 1, - "component_id": null, - "price_point_id": null - }, - { - "uid": "cnli_8kjttvjknzhx7", - "title": "Small Instance (Hourly)", - "description": "38.2% credit", - "quantity": "74.8676", - "unit_price": "0.12244898", - "subtotal_amount": "9.16746047", - "discount_amount": "0.91674605", - "tax_amount": "0.55692322", - "total_amount": "8.80763764", - "tiered_unit_price": true, - "period_range_start": "2018-11-30", - "period_range_end": "2018-11-30", - "product_id": 85, - "product_version": 1, - "component_id": 78, - "price_point_id": null - }, - { - "uid": "cnli_8kjttvjnmh25w", - "title": "Large Instance (Hourly)", - "description": "38.2% credit", - "quantity": "183.3492", - "unit_price": "0.39583333", - "subtotal_amount": "72.57572871", - "discount_amount": "7.25757287", - "tax_amount": "4.40897552", - "total_amount": "69.72713136", - "tiered_unit_price": true, - "period_range_start": "2018-11-30", - "period_range_end": "2018-11-30", - "product_id": 85, - "product_version": 1, - "component_id": 79, - "price_point_id": null - }, - { - "uid": "cnli_8kjttvjqn86kc", - "title": "Email Messages", - "description": "38.2% credit", - "quantity": "10076.9489", - "unit_price": "0.00031045", - "subtotal_amount": "3.12839588", - "discount_amount": "0.31322157", - "tax_amount": "0.19002427", - "total_amount": "3.00519858", - "tiered_unit_price": true, - "period_range_start": "2018-11-30", - "period_range_end": "2018-11-30", - "product_id": 85, - "product_version": 1, - "component_id": 80, - "price_point_id": null - }, - { - "uid": "cnli_8kjttvjtxxbdd", - "title": "IP Addresses", - "description": "38.2% credit", - "quantity": "3.8198", - "unit_price": "2.0", - "subtotal_amount": "7.63955039", - "discount_amount": "0.76395504", - "tax_amount": "0.46410269", - "total_amount": "7.33969804", - "tiered_unit_price": false, - "period_range_start": "2018-12-30", - "period_range_end": "2018-12-30", - "product_id": 85, - "product_version": 1, - "component_id": 81, - "price_point_id": 165 - } - ], - "discounts": [ - { - "uid": "cndli_8k5jvdzct4h9y", - "title": "Multi-service discount (10%)", - "code": "MULTI3", - "source_type": "Coupon", - "source_id": 40, - "discount_type": "percentage", - "percentage": "10.0", - "eligible_amount": "208.69341779", - "discount_amount": "20.87125167", - "line_item_breakouts": [ - { - "uid": "cnli_8k5jvdzct4h9x", - "eligible_amount": "1.971004", - "discount_amount": "0.19862831" - }, - { - "uid": "cnli_8kjttvjcjx8b4", - "eligible_amount": "114.21127834", - "discount_amount": "11.42112783" - }, - { - "uid": "cnli_8kjttvjknzhx7", - "eligible_amount": "9.16746047", - "discount_amount": "0.91674605" - }, - { - "uid": "cnli_8kjttvjnmh25w", - "eligible_amount": "72.57572871", - "discount_amount": "7.25757287" - }, - { - "uid": "cnli_8kjttvjqn86kc", - "eligible_amount": "3.12839588", - "discount_amount": "0.31322157" - }, - { - "uid": "cnli_8kjttvjtxxbdd", - "eligible_amount": "7.63955039", - "discount_amount": "0.76395504" - } - ] - } - ], - "taxes": [ - { - "uid": "cntli_8k5jvdzct4h9z", - "title": "NC Sales Tax", - "source_type": "Tax", - "source_id": 1, - "percentage": "6.75", - "taxable_amount": "187.82216613", - "tax_amount": "12.67783387", - "line_item_breakouts": [ - { - "uid": "cnli_8k5jvdzct4h9x", - "taxable_amount": "1.77237569", - "tax_amount": "0.11963536" - }, - { - "uid": "cnli_8kjttvjcjx8b4", - "taxable_amount": "102.7901505", - "tax_amount": "6.93833516" - }, - { - "uid": "cnli_8kjttvjknzhx7", - "taxable_amount": "8.25071442", - "tax_amount": "0.55692322" - }, - { - "uid": "cnli_8kjttvjnmh25w", - "taxable_amount": "65.31815584", - "tax_amount": "4.40897552" - }, - { - "uid": "cnli_8kjttvjqn86kc", - "taxable_amount": "2.81517432", - "tax_amount": "0.19002427" - }, - { - "uid": "cnli_8kjttvjtxxbdd", - "taxable_amount": "6.87559535", - "tax_amount": "0.46410269" - } - ] - } - ], - "applications": [ - { - "uid": "cdt_8m9vbdbdwd28n", - "transaction_time": "2018-12-31T21:19:28Z", - "invoice_uid": "inv_8k5jvdzct4hb2", - "memo": "Refund for overpayment", - "applied_amount": "200.5" - } - ], - "refunds": [ - { - "transaction_id": 329, - "payment_id": 39, - "memo": "Refund for overpayment", - "original_amount": "524.9", - "applied_amount": "200.5" - } - ] - } - ] - } - } - } - } - } - } - }, - "operationId": "listCreditNotes", - "description": "Credit Notes are like inverse invoices. They reduce the amount a customer owes.\n\nBy default, the credit notes returned by this endpoint will exclude the arrays of `line_items`, `discounts`, `taxes`, `applications`, or `refunds`. To include these arrays, pass the specific field as a key in the query with a value set to `true`.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "subscription_id", - "description": "The subscription's Chargify id" - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "line_items", - "description": "Include line items data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "discounts", - "description": "Include discounts data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "taxes", - "description": "Include taxes data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "refunds", - "description": "Include refunds data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "applications", - "description": "Include applications data" - } - ] - } - }, - "/credit_notes/{uid}.json": { - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "uid", - "in": "path", - "required": true, - "description": "The unique identifier of the credit note" - } - ], - "get": { - "summary": "Read Credit Note", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Credit-Note.yaml" - }, - "examples": { - "Example": { - "value": { - "uid": "cn_8m9vbd5kkv7kr", - "site_id": 20, - "customer_id": 3, - "subscription_id": 2, - "number": "77", - "sequence_number": 78, - "issue_date": "2018-12-31", - "applied_date": "2018-12-31", - "status": "applied", - "currency": "USD", - "memo": "Refund for overpayment", - "seller": { - "name": "Acme, Inc.", - "address": { - "street": "122 E Houston St", - "line2": "Suite 105", - "city": "San Antonio", - "state": "TX", - "zip": "78205", - "country": "US" - }, - "phone": "555-555-1234 x137" - }, - "customer": { - "chargify_id": 3, - "first_name": "Marty", - "last_name": "McFly", - "organization": "Time Travellers, Inc.", - "email": "timetraveller1985@example.com", - "reference": null - }, - "billing_address": { - "street": "200 Billing Rd.", - "line2": "Suite 100", - "city": "Needham", - "state": "MA", - "zip": "02494", - "country": "US" - }, - "shipping_address": { - "street": "100 Shipping St.", - "line2": "Apt 200", - "city": "Pleasantville", - "state": "NC", - "zip": "12345", - "country": "US" - }, - "subtotal_amount": "208.69341779", - "discount_amount": "20.87125167", - "tax_amount": "12.67783387", - "total_amount": "200.5", - "applied_amount": "200.5", - "remaining_amount": "0.0", - "line_items": [ - { - "uid": "cnli_8k5jvdzct4h9x", - "title": "IP Addresses: 5 to 10 addresses", - "description": "38.2% credit", - "quantity": "0.9855", - "unit_price": "2.0", - "subtotal_amount": "1.971004", - "discount_amount": "0.19862831", - "tax_amount": "0.11963536", - "total_amount": "1.89201105", - "tiered_unit_price": false, - "period_range_start": "2018-11-30", - "period_range_end": "2018-11-30", - "product_id": 85, - "product_version": 1, - "component_id": 81, - "price_point_id": 165, - "billing_schedule_item_id": null, - "custom_item": false - }, - { - "uid": "cnli_8kjttvjcjx8b4", - "title": "Professional Plan", - "description": "38.2% credit", - "quantity": "0.382", - "unit_price": "299.0", - "subtotal_amount": "114.21127834", - "discount_amount": "11.42112783", - "tax_amount": "6.93833516", - "total_amount": "109.72848567", - "tiered_unit_price": false, - "period_range_start": "2018-12-30", - "period_range_end": "2018-12-30", - "product_id": 85, - "product_version": 1, - "component_id": null, - "price_point_id": null, - "billing_schedule_item_id": null, - "custom_item": false - }, - { - "uid": "cnli_8kjttvjknzhx7", - "title": "Small Instance (Hourly)", - "description": "38.2% credit", - "quantity": "74.8676", - "unit_price": "0.12244898", - "subtotal_amount": "9.16746047", - "discount_amount": "0.91674605", - "tax_amount": "0.55692322", - "total_amount": "8.80763764", - "tiered_unit_price": true, - "period_range_start": "2018-11-30", - "period_range_end": "2018-11-30", - "product_id": 85, - "product_version": 1, - "component_id": 78, - "price_point_id": null, - "billing_schedule_item_id": null, - "custom_item": false - }, - { - "uid": "cnli_8kjttvjnmh25w", - "title": "Large Instance (Hourly)", - "description": "38.2% credit", - "quantity": "183.3492", - "unit_price": "0.39583333", - "subtotal_amount": "72.57572871", - "discount_amount": "7.25757287", - "tax_amount": "4.40897552", - "total_amount": "69.72713136", - "tiered_unit_price": true, - "period_range_start": "2018-11-30", - "period_range_end": "2018-11-30", - "product_id": 85, - "product_version": 1, - "component_id": 79, - "price_point_id": null, - "billing_schedule_item_id": null, - "custom_item": false - }, - { - "uid": "cnli_8kjttvjqn86kc", - "title": "Email Messages", - "description": "38.2% credit", - "quantity": "10076.9489", - "unit_price": "0.00031045", - "subtotal_amount": "3.12839588", - "discount_amount": "0.31322157", - "tax_amount": "0.19002427", - "total_amount": "3.00519858", - "tiered_unit_price": true, - "period_range_start": "2018-11-30", - "period_range_end": "2018-11-30", - "product_id": 85, - "product_version": 1, - "component_id": 80, - "price_point_id": null, - "billing_schedule_item_id": null, - "custom_item": false - }, - { - "uid": "cnli_8kjttvjtxxbdd", - "title": "IP Addresses", - "description": "38.2% credit", - "quantity": "3.8198", - "unit_price": "2.0", - "subtotal_amount": "7.63955039", - "discount_amount": "0.76395504", - "tax_amount": "0.46410269", - "total_amount": "7.33969804", - "tiered_unit_price": false, - "period_range_start": "2018-12-30", - "period_range_end": "2018-12-30", - "product_id": 85, - "product_version": 1, - "component_id": 81, - "price_point_id": 165, - "billing_schedule_item_id": null, - "custom_item": false - } - ], - "discounts": [ - { - "uid": "cndli_8k5jvdzct4h9y", - "title": "Multi-service discount (10%)", - "code": "MULTI3", - "source_type": "Coupon", - "source_id": 40, - "discount_type": "percentage", - "percentage": "10.0", - "eligible_amount": "208.69341779", - "discount_amount": "20.87125167", - "line_item_breakouts": [ - { - "uid": "cnli_8k5jvdzct4h9x", - "eligible_amount": "1.971004", - "discount_amount": "0.19862831" - }, - { - "uid": "cnli_8kjttvjcjx8b4", - "eligible_amount": "114.21127834", - "discount_amount": "11.42112783" - }, - { - "uid": "cnli_8kjttvjknzhx7", - "eligible_amount": "9.16746047", - "discount_amount": "0.91674605" - }, - { - "uid": "cnli_8kjttvjnmh25w", - "eligible_amount": "72.57572871", - "discount_amount": "7.25757287" - }, - { - "uid": "cnli_8kjttvjqn86kc", - "eligible_amount": "3.12839588", - "discount_amount": "0.31322157" - }, - { - "uid": "cnli_8kjttvjtxxbdd", - "eligible_amount": "7.63955039", - "discount_amount": "0.76395504" - } - ] - } - ], - "taxes": [ - { - "uid": "cntli_8k5jvdzct4h9z", - "title": "NC Sales Tax", - "source_type": "Tax", - "source_id": 1, - "percentage": "6.75", - "taxable_amount": "187.82216613", - "tax_amount": "12.67783387", - "line_item_breakouts": [ - { - "uid": "cnli_8k5jvdzct4h9x", - "taxable_amount": "1.77237569", - "tax_amount": "0.11963536" - }, - { - "uid": "cnli_8kjttvjcjx8b4", - "taxable_amount": "102.7901505", - "tax_amount": "6.93833516" - }, - { - "uid": "cnli_8kjttvjknzhx7", - "taxable_amount": "8.25071442", - "tax_amount": "0.55692322" - }, - { - "uid": "cnli_8kjttvjnmh25w", - "taxable_amount": "65.31815584", - "tax_amount": "4.40897552" - }, - { - "uid": "cnli_8kjttvjqn86kc", - "taxable_amount": "2.81517432", - "tax_amount": "0.19002427" - }, - { - "uid": "cnli_8kjttvjtxxbdd", - "taxable_amount": "6.87559535", - "tax_amount": "0.46410269" - } - ] - } - ], - "applications": [ - { - "uid": "cdt_8m9vbdbdwd28n", - "transaction_time": "2018-12-31T21:19:28Z", - "invoice_uid": "inv_8k5jvdzct4hb2", - "memo": "Refund for overpayment", - "applied_amount": "200.5" - } - ], - "refunds": [ - { - "transaction_id": 329, - "payment_id": 39, - "memo": "Refund for overpayment", - "original_amount": "524.9", - "applied_amount": "200.5" - } - ] - } - } - } - } - } - } - }, - "operationId": "readCreditNote", - "description": "Use this endpoint to retrieve the details for a credit note." - } - }, - "/subscriptions/{subscription_id}/payments.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Record Payment For Subscription", - "tags": [ - "Invoices" - ], - "responses": { - "201": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Record-Payment-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "paid_invoices": [ - { - "invoice_id": "inv_bchyhr6z5grby", - "status": "paid", - "due_amount": "0.0", - "paid_amount": "50.0" - }, - { - "invoice_id": "inv_bchyhrgvyb6vm", - "status": "paid", - "due_amount": "0.0", - "paid_amount": "50.0" - } - ], - "prepayment": null - } - }, - "Example-2": { - "value": { - "paid_invoices": [ - { - "invoice_id": "inv_bchyhr6z5grby", - "status": "open", - "due_amount": "10.0", - "paid_amount": "50.0" - } - ], - "prepayment": null - } - }, - "Example-3": { - "value": { - "paid_invoices": [ - { - "invoice_id": "inv_bchyhr6z5grby", - "status": "paid", - "due_amount": "0.0", - "paid_amount": "50.0" - }, - { - "invoice_id": "inv_bchyhrgvyb6vm", - "status": "paid", - "due_amount": "0.0", - "paid_amount": "50.0" - } - ], - "prepayment": { - "subscription_id": 123456, - "amount_in_cents": 9500, - "ending_balance_in_cents": 9500 - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Payment amount, details, method, and memo must be present", - "Payment amount, details, method, and memo must valid", - "Payment amount must be greater than zero", - "If in a group, the Subscription must be the primary" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "recordPaymentForSubscription", - "description": "Record an external payment made against a subscription that will pay partially or in full one or more invoices.\n\nPayment will be applied starting with the oldest open invoice and then next oldest, and so on until the amount of the payment is fully consumed.\n\nExcess payment will result in the creation of a prepayment on the Invoice Account.\n\nOnly ungrouped or primary subscriptions may be paid using the \"bulk\" payment request.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Record-Payment-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "payment": { - "amount": "10.0", - "memo": "to pay the bills", - "payment_details": "check number 8675309", - "payment_method": "check" - } - } - } - } - } - } - } - } - }, - "/invoices/{uid}/reopen.json": { - "parameters": [ - { - "$ref": "../components/parameters/invoice-uid-path.yaml" - } - ], - "post": { - "summary": "Reopen Invoice", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Invoice.yaml" - } - } - } - }, - "404": { - "description": "Not Found", - "content": { - "application/json": { - "schema": { - "type": "null" - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "The invoice must be in canceled status to be reopened." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "reopenInvoice", - "description": "This endpoint allows you to reopen any invoice with the \"canceled\" status. Invoices enter \"canceled\" status if they were open at the time the subscription was canceled (whether through dunning or an intentional cancellation).\n\nInvoices with \"canceled\" status are no longer considered to be due. Once reopened, they are considered due for payment. Payment may then be captured in one of the following ways:\n\n- Reactivating the subscription, which will capture all open invoices (See note below about automatic reopening of invoices.)\n- Recording a payment directly against the invoice\n\nA note about reactivations: any canceled invoices from the most recent active period are automatically opened as a part of the reactivation process. Reactivating via this endpoint prior to reactivation is only necessary when you wish to capture older invoices from previous periods during the reactivation.\n\n### Reopening Consolidated Invoices\n\nWhen reopening a consolidated invoice, all of its canceled segments will also be reopened." - } - }, - "/invoices/{uid}/void.json": { - "parameters": [ - { - "$ref": "../components/parameters/invoice-uid-path.yaml" - } - ], - "post": { - "summary": "Void Invoice", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Invoice.yaml" - } - } - } - }, - "404": { - "description": "Not Found", - "content": { - "application/json": { - "schema": { - "type": "null" - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Invoice status must be 'open', 'canceled', or 'pending' and non-consolidated to be voided." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "voidInvoice", - "description": "This endpoint allows you to void any invoice with the \"open\" or \"canceled\" status. It will also allow voiding of an invoice with the \"pending\" status if it is not a consolidated invoice.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Void-Invoice-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "void": { - "reason": "Duplicate invoice" - } - } - } - } - } - } - } - } - }, - "/invoices/{invoice_uid}/segments.json": { - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "invoice_uid", - "in": "path", - "required": true, - "description": "The unique identifier of the consolidated invoice" - } - ], - "get": { - "summary": "List Segments for Consolidated Invoice", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Consolidated-Invoice.yaml" - }, - "examples": { - "Example": { - "value": { - "invoices": [ - { - "uid": "inv_8htcd29wcq3q6", - "site_id": 51288, - "customer_id": 20153415, - "subscription_id": 23277588, - "number": "125", - "sequence_number": 125, - "issue_date": "2018-09-20", - "due_date": "2018-09-20", - "paid_date": "2018-09-20", - "status": "paid", - "collection_method": "automatic", - "payment_instructions": "Make checks payable to Acme, Inc.", - "currency": "USD", - "consolidation_level": "parent", - "parent_invoice_uid": null, - "parent_invoice_number": null, - "group_primary_subscription_id": 23277588, - "product_name": "Trial and setup fee", - "product_family_name": "Billing Plans", - "seller": { - "name": "General Goods", - "address": { - "street": "123 General Goods Way", - "line2": "Apt. 10", - "city": "Boston", - "state": "MA", - "zip": "02120", - "country": "US" - }, - "phone": "555-555-1212" - }, - "customer": { - "chargify_id": 20153415, - "first_name": "Meg", - "last_name": "Example", - "organization": "", - "email": "meg@example.com" - }, - "memo": "Please pay within 15 days.", - "billing_address": { - "street": "123 I Love Cats Way", - "line2": "", - "city": "Boston", - "state": "MA", - "zip": "90210", - "country": "US" - }, - "shipping_address": { - "street": "123 I Love Cats Way", - "line2": "", - "city": "Boston", - "state": "MA", - "zip": "90210", - "country": "US" - }, - "subtotal_amount": "100.0", - "discount_amount": "0.0", - "tax_amount": "0.0", - "total_amount": "100.0", - "credit_amount": "0.0", - "paid_amount": "100.0", - "refund_amount": "0.0", - "due_amount": "0.0", - "public_url": "https://www.chargifypay.com/invoice/inv_8htcd29wcq3q6?token=fb6kpjz5rcr2vttyjs4rcv6y" - }, - { - "uid": "inv_8hr3546xp4h8n", - "site_id": 51288, - "customer_id": 21687686, - "subscription_id": 22007644, - "number": "124", - "sequence_number": 124, - "issue_date": "2018-09-18", - "due_date": "2018-09-18", - "paid_date": null, - "status": "open", - "collection_method": "remittance", - "payment_instructions": "Make checks payable to Acme, Inc.", - "currency": "USD", - "consolidation_level": "none", - "parent_invoice_uid": null, - "parent_invoice_number": null, - "group_primary_subscription_id": null, - "product_name": "Trial and setup fee", - "product_family_name": "Billing Plans", - "seller": { - "name": "General Goods", - "address": { - "street": "123 General Goods Way", - "line2": "Apt. 10", - "city": "Boston", - "state": "MA", - "zip": "02120", - "country": "US" - }, - "phone": "555-555-1212" - }, - "customer": { - "chargify_id": 21687686, - "first_name": "Charlene", - "last_name": "Tester", - "organization": "", - "email": "food@example.com" - }, - "memo": "Please pay within 15 days.", - "billing_address": { - "street": "", - "line2": "", - "city": "", - "state": "", - "zip": "", - "country": "" - }, - "shipping_address": { - "street": "", - "line2": "", - "city": "", - "state": "", - "zip": "", - "country": "" - }, - "subtotal_amount": "100.0", - "discount_amount": "0.0", - "tax_amount": "0.0", - "total_amount": "100.0", - "credit_amount": "0.0", - "paid_amount": "0.0", - "refund_amount": "0.0", - "due_amount": "100.0", - "public_url": "https://www.chargifypay.com/invoice/inv_8hr3546xp4h8n?token=fb6kpjz5rcr2vttyjs4rcv6y" - }, - { - "uid": "inv_8hr3546wdwxkr", - "site_id": 51288, - "customer_id": 21687670, - "subscription_id": 22007627, - "number": "123", - "sequence_number": 123, - "issue_date": "2018-09-18", - "due_date": "2018-09-18", - "paid_date": "2018-09-18", - "status": "paid", - "collection_method": "automatic", - "payment_instructions": "Make checks payable to Acme, Inc.", - "currency": "USD", - "consolidation_level": "none", - "parent_invoice_uid": null, - "parent_invoice_number": null, - "group_primary_subscription_id": null, - "product_name": "Trial End - Free", - "product_family_name": "Billing Plans", - "seller": { - "name": "General Goods", - "address": { - "street": "123 General Goods Way", - "line2": "Apt. 10", - "city": "Boston", - "state": "MA", - "zip": "02120", - "country": "US" - }, - "phone": "555-555-1212" - }, - "customer": { - "chargify_id": 21687670, - "first_name": "Hello", - "last_name": "World", - "organization": "123", - "email": "example@example.com" - }, - "memo": "Please pay within 15 days.", - "billing_address": { - "street": "123 Anywhere Street", - "line2": "", - "city": "Boston", - "state": "MA", - "zip": "02120", - "country": "US" - }, - "shipping_address": { - "street": "", - "line2": "", - "city": "Boston", - "state": "AL", - "zip": "02120", - "country": "US" - }, - "subtotal_amount": "0.0", - "discount_amount": "0.0", - "tax_amount": "0.0", - "total_amount": "0.0", - "credit_amount": "0.0", - "paid_amount": "0.0", - "refund_amount": "0.0", - "due_amount": "0.0", - "public_url": "https://www.chargifypay.com/invoice/inv_8hr3546wdwxkr?token=fb6kpjz5rcr2vttyjs4rcv6y" - }, - { - "uid": "inv_8hjtk8bz56bbp", - "site_id": 51288, - "customer_id": 20137757, - "subscription_id": 20541100, - "number": "122", - "sequence_number": 122, - "issue_date": "2018-09-10", - "due_date": "2018-09-10", - "paid_date": "2018-09-10", - "status": "paid", - "collection_method": "automatic", - "payment_instructions": "Make checks payable to Acme, Inc.", - "currency": "USD", - "consolidation_level": "none", - "parent_invoice_uid": null, - "parent_invoice_number": null, - "group_primary_subscription_id": null, - "product_name": "$0 Product", - "product_family_name": "Billing Plans", - "seller": { - "name": "General Goods", - "address": { - "street": "123 General Goods Way", - "line2": "Apt. 10", - "city": "Boston", - "state": "MA", - "zip": "02120", - "country": "US" - }, - "phone": "555-555-1212" - }, - "customer": { - "chargify_id": 20137757, - "first_name": "Sasha", - "last_name": "Example", - "organization": "", - "email": "example@example.com" - }, - "memo": "Please pay within 15 days.", - "billing_address": { - "street": "123 I Love Cats Way", - "line2": "", - "city": "Catville", - "state": "MA", - "zip": "90210", - "country": "US" - }, - "shipping_address": { - "street": "123 I Love Cats Way", - "line2": "", - "city": "Catville", - "state": "AL", - "zip": "90210", - "country": "US" - }, - "subtotal_amount": "0.0", - "discount_amount": "0.0", - "tax_amount": "0.0", - "total_amount": "0.0", - "credit_amount": "0.0", - "paid_amount": "0.0", - "refund_amount": "0.0", - "due_amount": "0.0", - "public_url": "https://www.chargifypay.com/invoice/inv_8jzrw74xq8kxr?token=fb6kpjz5rcr2vttyjs4rcv6y" - } - ] - } - } - } - } - } - } - }, - "operationId": "listConsolidatedInvoiceSegments", - "description": "Invoice segments returned on the index will only include totals, not detailed breakdowns for `line_items`, `discounts`, `taxes`, `credits`, `payments`, or `custom_fields`.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "string", - "default": "asc", - "enum": [ - "asc", - "desc" - ] - }, - "in": "query", - "name": "direction", - "description": "Sort direction of the returned segments." - } - ] - } - }, - "/subscriptions/{subscription_id}/account_balances.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "get": { - "summary": "Read Account Balances", - "tags": [ - "Subscription Invoice Account" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Account-Balances.yaml" - } - } - } - } - }, - "operationId": "readAccountBalances", - "description": "Returns the `balance_in_cents` of the Subscription's Pending Discount, Service Credit, and Prepayment accounts, as well as the sum of the Subscription's open, payable invoices." - } - }, - "/subscriptions/{subscription_id}/components/{component_id}.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - }, - { - "schema": { - "type": "integer" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "The Chargify id of the component. Alternatively, the component's handle prefixed by `handle:`" - } - ], - "get": { - "summary": "Read Subscription Component", - "tags": [ - "Subscription Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Component-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "component": { - "component_id": 193028, - "subscription_id": 14593192, - "allocated_quantity": 1, - "pricing_scheme": "per_unit", - "name": "Users", - "kind": "quantity_based_component", - "unit_name": "Users", - "price_point_id": 1, - "price_point_handle": "top-tier", - "enabled": true - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "readSubscriptionComponent", - "description": "This request will list information regarding a specific component owned by a subscription." - } - }, - "/subscriptions/{subscription_id}/components.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "get": { - "summary": "List Subscription Components", - "tags": [ - "Subscription Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Subscription-Component-Response.yaml" - } - }, - "examples": { - "example-1": { - "value": [ - { - "component": { - "component_id": 0, - "subscription_id": 0, - "allocated_quantity": 0, - "pricing_scheme": "per_unit", - "name": "string", - "kind": "quantity_based_component", - "unit_name": "string", - "price_point_id": 0, - "price_point_handle": "string", - "price_point_type": "default", - "price_point_name": "string", - "enabled": true, - "unit_balance": 0, - "id": 0, - "created_at": "2022-02-22T14:07:00-05:00", - "updated_at": "2022-02-22T14:07:00-05:00", - "component_handle": "string", - "archived_at": null - } - } - ] - } - } - } - } - } - }, - "operationId": "listSubscriptionComponents", - "description": "This request will list a subscription's applied components.\n\n## Archived Components\n\nWhen requesting to list components for a given subscription, if the subscription contains **archived** components they will be listed in the server response.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "schema": { - "$ref": "../components/schemas/Subscription-List-Date-Field.yaml" - }, - "in": "query", - "name": "date_field", - "description": "The type of filter you'd like to apply to your search. Use in query `date_field=updated_at`." - }, - { - "$ref": "../components/parameters/sort-direction.yaml" - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_date", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of end_date.", - "name": "end_datetime" - }, - { - "schema": { - "$ref": "../components/schemas/Include-Not-Null.yaml" - }, - "in": "query", - "name": "price_point_ids", - "description": "Allows fetching components allocation only if price point id is present. Use in query `price_point_ids=not_null`." - }, - { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [ - 1, - 2, - 3 - ] - }, - "style": "form", - "explode": false, - "in": "query", - "description": "Allows fetching components allocation with matching product family id based on provided ids. Use in query `product_family_ids=1,2,3`.", - "name": "product_family_ids" - }, - { - "schema": { - "$ref": "../components/schemas/List-Subscription-Components-Sort.yaml" - }, - "in": "query", - "name": "sort", - "description": "The attribute by which to sort. Use in query `sort=updated_at`." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_date", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_datetime", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of start_date." - }, - { - "schema": { - "$ref": "../components/schemas/List-Subscription-Components-Include.yaml" - }, - "in": "query", - "description": "Allows including additional data in the response. Use in query `include=subscription`.", - "name": "include" - }, - { - "schema": { - "type": "boolean", - "example": true - }, - "in": "query", - "description": "Allows fetching components allocation with matching use_site_exchange_rate based on provided value. Use in query `filter[use_site_exchange_rate]=true`.", - "name": "filter[use_site_exchange_rate]" - }, - { - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "EUR", - "USD" - ] - }, - "style": "form", - "explode": false, - "in": "query", - "description": "Allows fetching components allocation with matching currency based on provided values. Use in query `filter[currencies]=EUR,USD`.", - "name": "filter[currencies]" - } - ] - } - }, - "/subscriptions/{subscription_id}/price_points.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Bulk Update Subscription Components' Price Points", - "tags": [ - "Subscription Components" - ], - "operationId": "bulkUpdateSubscriptionComponentsPricePoints", - "description": "Updates the price points on one or more of a subscription's components.\n\nThe `price_point` key can take either a:\n1. Price point id (integer)\n2. Price point handle (string)\n3. `\"_default\"` string, which will reset the price point to the component's current default price point.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Bulk-Components-Price-Point-Assignment.yaml" - }, - "examples": { - "Example": { - "value": { - "components": [ - { - "component_id": 997, - "price_point": 1022 - }, - { - "component_id": 998, - "price_point": "wholesale-handle" - }, - { - "component_id": 999, - "price_point": "_default" - } - ] - } - } - } - } - }, - "description": "" - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Bulk-Components-Price-Point-Assignment.yaml" - }, - "examples": { - "Example": { - "value": { - "components": [ - { - "component_id": 123, - "price_point": 456 - }, - { - "component_id": 789, - "price_point": 987 - } - ] - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Component-PricePoint-Error.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - { - "component_id": 6474, - "price_point": 12140, - "message": "Price Point does not belong to Component" - } - ] - } - } - } - } - } - } - } - } - }, - "/subscriptions/{subscription_id}/price_points/reset.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Bulk Reset Subscription Components' Price Points", - "tags": [ - "Subscription Components" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "id": 80293620, - "state": "active", - "trial_started_at": null, - "trial_ended_at": null, - "activated_at": "2023-11-23T10:28:34-05:00", - "created_at": "2023-11-23T10:28:34-05:00", - "updated_at": "2023-11-23T10:28:34-05:00", - "expires_at": null, - "balance_in_cents": 50504234, - "current_period_ends_at": "2023-11-23T10:28:34-05:00", - "next_assessment_at": "2023-11-23T10:28:34-05:00", - "canceled_at": null, - "cancellation_message": "lorem ipsum", - "next_product_id": null, - "cancel_at_end_of_period": false, - "payment_collection_method": "remittance", - "snap_day": null, - "cancellation_method": "dunning", - "current_period_started_at": "2023-11-23T10:28:34-05:00", - "previous_state": "active", - "signup_payment_id": -45156092, - "signup_revenue": "do aliquip ea", - "delayed_cancel_at": null, - "coupon_code": null, - "total_revenue_in_cents": -49740952, - "product_price_in_cents": 87617888, - "product_version_number": 13656635, - "payment_type": null, - "referral_code": null, - "coupon_use_count": null, - "coupon_uses_allowed": null, - "reason_code": null, - "automatically_resume_at": null, - "current_billing_amount_in_cents": -26151968, - "customer": { - "id": 15208337, - "first_name": "ipsum culpa in labore eiusmod", - "last_name": "esse", - "organization": null, - "email": "ex eiusmod", - "created_at": "2021-05-05T16:00:21-04:00", - "updated_at": "2021-05-05T16:00:21-04:00", - "reference": "laboris ea cupidatat", - "address": null, - "address_2": null, - "city": "id eiusmod proident", - "state": "magna eiusmod anim non", - "zip": null, - "country": null, - "phone": null, - "portal_invite_last_sent_at": null, - "portal_invite_last_accepted_at": "2021-05-05T20:00:21-04:00", - "portal_customer_created_at": "2021-05-05T16:00:21-04:00", - "cc_emails": "eiusmod sunt", - "tax_exempt": true - }, - "product": { - "id": -74447756, - "name": "eu mollit nulla ut aute", - "handle": "esse dolor anim", - "description": "Lorem ut et non", - "accounting_code": "nisi", - "request_credit_card": false, - "expiration_interval": 1, - "expiration_interval_unit": "day", - "created_at": "2022-11-23T10:28:34-05:00", - "updated_at": "2022-11-23T10:28:34-05:00", - "price_in_cents": -4151649, - "interval": 20680876, - "interval_unit": "day", - "initial_charge_in_cents": null, - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": "day", - "archived_at": null, - "require_credit_card": true, - "return_params": "magna eu", - "taxable": true, - "update_return_url": "exercitation in", - "tax_code": "Excepteur aliqua sunt in", - "initial_charge_after_trial": true, - "version_number": 41642597, - "update_return_params": "dolore labore", - "product_family": { - "id": -5356997, - "name": "officia amet Lorem proident enim", - "description": "Duis", - "handle": "ea dolore dolore sunt", - "accounting_code": null - }, - "public_signup_pages": [] - } - } - } - } - } - } - } - } - }, - "operationId": "bulkResetSubscriptionComponentsPricePoints", - "description": "Resets all of a subscription's components to use the current default.\n\n**Note**: this will update the price point for all of the subscription's components, even ones that have not been allocated yet." - } - }, - "/subscriptions/{subscription_id}/components/{component_id}/allocations.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - }, - { - "schema": { - "type": "integer" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "The Chargify id of the component" - } - ], - "post": { - "summary": "Allocate Component", - "tags": [ - "Subscription Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Allocation-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "allocation": { - "component_id": 4034995, - "subscription_id": 23737320, - "quantity": 3, - "previous_quantity": 2, - "memo": "dolore cupidatat elit", - "timestamp": "2022-11-23T10:28:34-05:00", - "proration_upgrade_scheme": "laboris ipsum dolore", - "proration_downgrade_scheme": "eiusmod dolore", - "price_point_id": -69720370, - "previous_price_point_id": -76493052, - "accrue_charge": true, - "upgrade_charge": "full", - "downgrade_credit": "full", - "payment": { - "id": -44566528, - "amount_in_cents": 123, - "success": false, - "memo": "aliqua" - } - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "One or more allocation changes are required." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "allocateComponent", - "description": "This endpoint creates a new allocation, setting the current allocated quantity for the Component and recording a memo.\n\n**Notice**: Allocations can only be updated for Quantity, On/Off, and Prepaid Components.\n\n## Allocations Documentation\n\nFull documentation on how to record Allocations in the Chargify UI can be located [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404527849997). It is focused on how allocations operate within the Chargify UI.It goes into greater detail on how the user interface will react when recording allocations.\n\nThis documentation also goes into greater detail on how proration is taken into consideration when applying component allocations.\n\n## Proration Schemes\n\nChanging the allocated quantity of a component mid-period can result in either a Charge or Credit being applied to the subscription. When creating an allocation via the API, you can pass the `upgrade_charge`, `downgrade_credit`, and `accrue_charge` to be applied.\n\n**Notice:** These proration and accural fields will be ignored for Prepaid Components since this component type always generate charges immediately without proration.\n\nFor background information on prorated components and upgrade/downgrade schemes, see [Setting Component Allocations.](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404527849997#proration-upgrades-vs-downgrades).\nSee the tables below for valid values.\n\n| upgrade_charge | Definition                                                        |\n|----------------|-------------------------------------------------------------------|\n| `full`         | A charge is added for the full price of the component.            |\n| `prorated`     | A charge is added for the prorated price of the component change. |\n| `none`         | No charge is added.                                               |\n\n| downgrade_credit | Definition                                        |\n|------------------|---------------------------------------------------|\n| `full`           | A full price credit is added for the amount owed. |\n| `prorated`       | A prorated credit is added for the amount owed.   |\n| `none`           | No charge is added.                               |\n\n| accrue_charge | Definition                                                                                               |\n|---------------|------------------------------------------------------------------------------------------------------------|\n| `true`        | Attempt to charge the customer at next renewal. |\n| `false`       | Attempt to charge the customer right away. If it fails, the charge will be accrued until the next renewal. |\n\n### Order of Resolution for upgrade_charge and downgrade_credit\n\n1. Per allocation in API call (within a single allocation of the `allocations` array)\n2. [Component-level default value](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404527849997-Component-Allocations#component-allocations-0-0)\n3. Allocation API call top level (outside of the `allocations` array)\n4. [Site-level default value](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404527849997#proration-schemes)\n\n### Order of Resolution for accrue charge\n\n1. Allocation API call top level (outside of the `allocations` array)\n2. [Site-level default value](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404527849997#proration-schemes)\n\n**NOTE: Proration uses the current price of the component as well as the current tax rates. Changes to either may cause the prorated charge/credit to be wrong.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Allocation-Request.yaml" - }, - "examples": { - "Quantity Based": { - "value": { - "allocation": { - "quantity": 5, - "memo": "Recoding component purchase of Acme Support" - } - } - }, - "On/Off Component (Toggle On)": { - "value": { - "allocation": { - "quantity": 1, - "memo": "Recoding component purchase of Acme Support" - } - } - }, - "On/Off Component (Toggle Off)": { - "value": { - "allocation": { - "quantity": 0, - "memo": "Recoding component purchase of Acme Support" - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Allocations", - "tags": [ - "Subscription Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Allocation-Response.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "allocation": { - "allocation_id": 2370199, - "component_id": 41028, - "subscription_id": 352827, - "quantity": 10, - "previous_quantity": 0, - "memo": "Recoding component allocation", - "timestamp": "2024-02-28T09:31:05Z", - "proration_upgrade_scheme": "full-price-attempt-capture", - "proration_downgrade_scheme": "no-prorate", - "price_point_id": 2957424, - "price_point_handle": "uuid:03190e20-b84a-013c-ca77-0286551bb34f", - "price_point_name": "Original", - "previous_price_point_id": 2957424, - "component_handle": "test-prepaid-component-4982065948", - "accrue_charge": false, - "upgrade_charge": "full", - "downgrade_credit": "none", - "created_at": "2024-02-28T04:31:05-05:00", - "initiate_dunning": false, - "expires_at": "2024-08-03T20:00:00-04:00", - "used_quantity": 5, - "charge_id": 11586076 - } - }, - { - "allocation": { - "memo": null, - "timestamp": "2012-11-20T21:48:09Z", - "quantity": 3, - "previous_quantity": 0, - "component_id": 11960, - "subscription_id": 2585595, - "proration_upgrade_scheme": "no-prorate", - "proration_downgrade_scheme": "no-prorate" - } - } - ] - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "invalid page: 0" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "listAllocations", - "description": "This endpoint returns the 50 most recent Allocations, ordered by most recent first.\n\n## On/Off Components\n\nWhen a subscription's on/off component has been toggled to on (`1`) or off (`0`), usage will be logged in this response.\n\n## Querying data via Chargify gem\n\nYou can also query the current quantity via the [official Chargify Gem.](http://github.com/chargify/chargify_api_ares)\n\n```# First way\ncomponent = Chargify::Subscription::Component.find(1, :params => {:subscription_id => 7})\nputs component.allocated_quantity\n# => 23\n\n# Second way\ncomponent = Chargify::Subscription.find(7).component(1)\nputs component.allocated_quantity\n# => 23\n```", - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - } - ] - } - }, - "/subscriptions/{subscription_id}/allocations.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Allocate Components", - "tags": [ - "Subscription Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Allocation-Response.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "allocation": { - "component_id": 193159, - "subscription_id": 15540611, - "quantity": 10, - "previous_quantity": 0, - "memo": "foo", - "timestamp": "2016-12-08T19:09:15Z", - "proration_upgrade_scheme": "prorate-attempt-capture", - "proration_downgrade_scheme": "no-prorate", - "payment": { - "amount_in_cents": 1451, - "success": true, - "memo": "Payment for: Prorated component allocation changes.", - "id": 165473487 - } - } - }, - { - "allocation": { - "component_id": 277221, - "subscription_id": 15540611, - "quantity": 5, - "previous_quantity": 0, - "memo": "bar", - "timestamp": "2016-12-08T19:09:15Z", - "proration_upgrade_scheme": "prorate-attempt-capture", - "proration_downgrade_scheme": "no-prorate", - "payment": { - "amount_in_cents": 1451, - "success": true, - "memo": "Payment for: Prorated component allocation changes.", - "id": 165473487 - } - } - } - ] - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Quantity: cannot be blank." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "allocateComponents", - "description": "Creates multiple allocations, setting the current allocated quantity for each of the components and recording a memo. The charges and/or credits that are created will be rolled up into a single total which is used to determine whether this is an upgrade or a downgrade. Be aware of the Order of Resolutions explained below in determining the proration scheme.\n\nA `component_id` is required for each allocation.\n\nThis endpoint only responds to JSON. It is not available for XML.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Allocate-Components.yaml" - }, - "examples": { - "Example": { - "value": { - "proration_upgrade_scheme": "prorate-attempt-capture", - "proration_downgrade_scheme": "no-prorate", - "allocations": [ - { - "component_id": 123, - "quantity": 10, - "memo": "foo" - }, - { - "component_id": 456, - "quantity": 5, - "memo": "bar" - } - ] - } - } - } - } - } - } - } - }, - "/subscriptions/{subscription_id}/allocations/preview.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Preview Allocations", - "tags": [ - "Subscription Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Allocation-Preview-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "allocation_preview": { - "start_date": "2019-05-02T15:26:46Z", - "end_date": "2019-05-08T15:26:46Z", - "period_type": "prorated", - "total_in_cents": 150, - "total_discount_in_cents": 0, - "total_tax_in_cents": 0, - "subtotal_in_cents": 150, - "existing_balance_in_cents": 0, - "accrue_charge": true, - "line_items": [ - { - "direction": "upgrade", - "transaction_type": "charge", - "kind": "quantity_based_component", - "amount_in_cents": 100, - "taxable_amount_in_cents": 0, - "discount_amount_in_cents": 0, - "memo": "Foo: 0 to 10 foo", - "component_id": 123, - "component_handle": "foo" - }, - { - "direction": "downgrade", - "transaction_type": "credit", - "kind": "quantity_based_component", - "amount_in_cents": -20, - "taxable_amount_in_cents": 0, - "discount_amount_in_cents": 0, - "memo": "Foo: 10 to 5 bar", - "component_id": 456, - "component_handle": "bar" - }, - { - "direction": "upgrade", - "transaction_type": "credit", - "kind": "quantity_based_component", - "amount_in_cents": 70, - "taxable_amount_in_cents": 0, - "discount_amount_in_cents": 0, - "memo": "Foo: 0 to 10 baz", - "component_id": 789, - "component_handle": "baz" - } - ], - "allocations": [ - { - "accrue_charge": true, - "upgrade_charge": "prorated", - "downgrade_credit": "full", - "component_handle": "foo", - "component_id": 123, - "memo": "foo", - "previous_price_point_id": 123, - "previous_quantity": 0, - "price_point_id": 123, - "proration_downgrade_scheme": "full", - "proration_upgrade_scheme": "prorate-delay-capture", - "quantity": 10, - "subscription_id": 123456, - "timestamp": null - }, - { - "accrue_charge": true, - "upgrade_charge": "full", - "downgrade_credit": "prorated", - "component_handle": "bar", - "component_id": 456, - "memo": "foo", - "previous_price_point_id": 456, - "previous_quantity": 10, - "price_point_id": 456, - "proration_downgrade_scheme": "prorate", - "proration_upgrade_scheme": "full-price-delay-capture", - "quantity": 5, - "subscription_id": 123456, - "timestamp": null - }, - { - "accrue_charge": true, - "upgrade_charge": "full", - "downgrade_credit": "none", - "component_handle": "baz", - "component_id": 789, - "memo": "foo", - "previous_price_point_id": 789, - "previous_quantity": 0, - "price_point_id": 789, - "proration_downgrade_scheme": "no-prorate", - "proration_upgrade_scheme": "full-price-delay-capture", - "quantity": 10, - "subscription_id": 123456, - "timestamp": null - } - ] - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Component-Allocation-Error.yaml", - "type": "object" - }, - "examples": { - "Example": { - "value": { - "errors": [ - { - "kind": "allocation", - "component_id": 379512, - "on": "base", - "message": "Allocations can only be updated for quantity and on/off components." - } - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "previewAllocations", - "description": "Chargify offers the ability to preview a potential subscription's **quantity-based** or **on/off** component allocation in the middle of the current billing period. This is useful if you want users to be able to see the effect of a component operation before actually doing it.\n\n## Fine-grained Component Control: Use with multiple `upgrade_charge`s or `downgrade_credits`\n\nWhen the allocation uses multiple different types of `upgrade_charge`s or `downgrade_credit`s, the Allocation is viewed as an Allocation which uses \"Fine-Grained Component Control\". As a result, the response will not include `direction` and `proration` within the `allocation_preview`, but at the `line_items` and `allocations` level respectfully.\n\nSee example below for Fine-Grained Component Control response.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Preview-Allocations-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "allocations": [ - { - "proration_upgrade_scheme": "prorate-attempt-capture", - "proration_downgrade_scheme": "prorate", - "component_id": 554108, - "price_point_id": 325826, - "quantity": 10, - "memo": "NOW" - } - ], - "effective_proration_date": "2023-11-01" - } - } - } - } - } - } - } - }, - "/subscriptions/{subscription_id}/components/{component_id}/allocations/{allocation_id}.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - }, - { - "schema": { - "type": "integer" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "The Chargify id of the component" - }, - { - "schema": { - "type": "integer" - }, - "name": "allocation_id", - "in": "path", - "required": true, - "description": "The Chargify id of the allocation" - } - ], - "put": { - "summary": "Update Prepaid Usage Allocation Expiration Date", - "tags": [ - "Subscription Components" - ], - "responses": { - "204": { - "description": "OK" - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Subscription-Component-Allocation-Error.yaml" - }, - "examples": { - "Example-1": { - "value": { - "errors": [ - { - "kind": "base", - "message": "A valid expires_at date must be provided." - } - ] - } - }, - "Example-2": { - "value": { - "errors": [ - { - "kind": "base", - "message": "Expires at: must be greater than or equal to 2024-02-28" - } - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updatePrepaidUsageAllocationExpirationDate", - "description": "When the expiration interval options are selected on a prepaid usage component price point, all allocations will be created with an expiration date. This expiration date can be changed after the fact to allow for extending or shortening the allocation's active window.\n\nIn order to change a prepaid usage allocation's expiration date, a PUT call must be made to the allocation's endpoint with a new expiration date.\n\n## Limitations\n\nA few limitations exist when changing an allocation's expiration date:\n\n- An expiration date can only be changed for an allocation that belongs to a price point with expiration interval options explicitly set.\n- An expiration date can be changed towards the future with no limitations.\n- An expiration date can be changed towards the past (essentially expiring it) up to the subscription's current period beginning date.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Allocation-Expiration-Date.yaml" - }, - "examples": { - "Example": { - "value": { - "allocation": { - "expires_at": "2021-05-05T16:00:00" - } - } - } - } - } - } - } - }, - "delete": { - "summary": "Delete Prepaid Usage Allocation", - "tags": [ - "Subscription Components" - ], - "responses": { - "200": { - "description": "OK" - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Subscription-Component-Allocation-Error.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - { - "kind": "base", - "message": "Credit scheme must be one of credit, refund or none." - } - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "deletePrepaidUsageAllocation", - "description": "Prepaid Usage components are unique in that their allocations are always additive. In order to reduce a subscription's allocated quantity for a prepaid usage component each allocation must be destroyed individually via this endpoint.\n\n## Credit Scheme\n\nBy default, destroying an allocation will generate a service credit on the subscription. This behavior can be modified with the optional `credit_scheme` parameter on this endpoint. The accepted values are:\n\n1. `none`: The allocation will be destroyed and the balances will be updated but no service credit or refund will be created.\n2. `credit`: The allocation will be destroyed and the balances will be updated and a service credit will be generated. This is also the default behavior if the `credit_scheme` param is not passed.\n3. `refund`: The allocation will be destroyed and the balances will be updated and a refund will be issued along with a Credit Note.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Credit-Scheme-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "credit_scheme": "none" - } - } - } - } - } - } - } - }, - "/subscriptions/{subscription_id}/components/{component_id}/usages.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - }, - { - "schema": { - "oneOf": [ - { - "type": "integer" - }, - { - "type": "string" - } - ] - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "Either the Chargify id for the component or the component's handle prefixed by `handle:`" - } - ], - "post": { - "summary": "Create Usage", - "tags": [ - "Subscription Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Usage-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "usage": { - "id": 138522957, - "memo": "My memo", - "created_at": "2017-11-13T10:05:32-06:00", - "price_point_id": 149416, - "quantity": 1000, - "component_id": 500093, - "component_handle": "handle", - "subscription_id": 22824464 - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Price point: could not be found." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createUsage", - "description": "## Documentation\n\nFull documentation on how to create Components in the Chargify UI can be located [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405020625677#creating-components). Additionally, for information on how to record component usage against a subscription, please see the following resources:\n\n+ [Recording Metered Component Usage](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404527849997#reporting-metered-component-usage)\n+ [Reporting Prepaid Component Status](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404527849997#reporting-prepaid-component-status)\n\nYou may choose to report metered or prepaid usage to Chargify as often as you wish. You may report usage as it happens. You may also report usage periodically, such as each night or once per billing period. If usage events occur in your system very frequently (on the order of thousands of times an hour), it is best to accumulate usage into batches on your side, and then report those batches less frequently, such as daily. This will ensure you remain below any API throttling limits. If your use case requires higher rates of usage reporting, we recommend utilizing Events Based Components.\n\n## Create Usage for Subscription\n\nThis endpoint allows you to record an instance of metered or prepaid usage for a subscription. The `quantity` from usage for each component is accumulated to the `unit_balance` on the [Component Line Item](./b3A6MTQxMDgzNzQ-read-subscription-component) for the subscription.\n\n## Price Point ID usage\n\nIf you are using price points, for metered and prepaid usage components, Chargify gives you the option to specify a price point in your request.\n\nYou do not need to specify a price point ID. If a price point is not included, the default price point for the component will be used when the usage is recorded.\n\nIf an invalid `price_point_id` is submitted, the endpoint will return an error.\n\n## Deducting Usage\n\nIn the event that you need to reverse a previous usage report or otherwise deduct from the current usage balance, you may provide a negative quantity.\n\nExample:\n\nPreviously recorded:\n\n```json\n{\n \"usage\": {\n \"quantity\": 5000,\n \"memo\": \"Recording 5000 units\"\n }\n}\n```\n\nAt this point, `unit_balance` would be `5000`. To reduce the balance to `0`, POST the following payload:\n\n```json\n{\n \"usage\": {\n \"quantity\": -5000,\n \"memo\": \"Deducting 5000 units\"\n }\n}\n```\n\nThe `unit_balance` has a floor of `0`; negative unit balances are never allowed. For example, if the usage balance is 100 and you deduct 200 units, the unit balance would then be `0`, not `-100`.\n\n## FAQ\n\nQ. Is it possible to record metered usage for more than one component at a time?\n\nA. No. Usage should be reported as one API call per component on a single subscription. For example, to record that a subscriber has sent both an SMS Message and an Email, send an API call for each.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Usage-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "usage": { - "quantity": 1000, - "price_point_id": "149416", - "memo": "My memo" - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Usages", - "tags": [ - "Subscription Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Usage-Response.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "usage": { - "id": 178534642, - "memo": "20", - "created_at": "2018-08-03T11:58:42-05:00", - "price_point_id": 242632, - "quantity": "20.0", - "component_id": 500093, - "component_handle": "handle", - "subscription_id": 22824464 - } - }, - { - "usage": { - "id": 178534591, - "memo": "10", - "created_at": "2018-08-03T11:58:29-05:00", - "price_point_id": 242632, - "quantity": "10.0", - "component_id": 500093, - "component_handle": "handle", - "subscription_id": 22824464 - } - } - ] - } - } - } - } - } - }, - "operationId": "listUsages", - "description": "This request will return a list of the usages associated with a subscription for a particular metered component. This will display the previously recorded components for a subscription.\n\nThis endpoint is not compatible with quantity-based components.\n\n## Since Date and Until Date Usage\n\nNote: The `since_date` and `until_date` attributes each default to midnight on the date specified. For example, in order to list usages for January 20th, you would need to append the following to the URL.\n\n```\n?since_date=2016-01-20&until_date=2016-01-21\n```\n\n## Read Usage by Handle\n\nUse this endpoint to read the previously recorded components for a subscription. You can now specify either the component id (integer) or the component handle prefixed by \"handle:\" to specify the unique identifier for the component you are working with.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "since_id", - "description": "Returns usages with an id greater than or equal to the one specified" - }, - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "max_id", - "description": "Returns usages with an id less than or equal to the one specified" - }, - { - "schema": { - "type": "string", - "format": "date" - }, - "in": "query", - "name": "since_date", - "description": "Returns usages with a created_at date greater than or equal to midnight (12:00 AM) on the date specified." - }, - { - "schema": { - "type": "string", - "format": "date" - }, - "in": "query", - "name": "until_date", - "description": "Returns usages with a created_at date less than or equal to midnight (12:00 AM) on the date specified." - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - } - ] - } - }, - "/event_based_billing/subscriptions/{subscription_id}/components/{component_id}/activate.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "subscription_id", - "in": "path", - "required": true, - "description": "The Chargify id of the subscription" - }, - { - "schema": { - "type": "integer" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "The Chargify id of the component" - } - ], - "post": { - "summary": "Activate Event-Based Component", - "tags": [ - "Subscription Components" - ], - "responses": { - "200": { - "description": "OK" - } - }, - "operationId": "activateEventBasedComponent", - "description": "In order to bill your subscribers on your Events data under the Events-Based Billing feature, the components must be activated for the subscriber.\n\nLearn more about the role of activation in the [Events-Based Billing docs](https://chargify.zendesk.com/hc/en-us/articles/4407720810907#activating-components-for-subscribers).\n\nUse this endpoint to activate an event-based component for a single subscription. Activating an event-based component causes Chargify to bill for events when the subscription is renewed.\n\n*Note: it is possible to stream events for a subscription at any time, regardless of component activation status. The activation status only determines if the subscription should be billed for event-based component usage at renewal.*" - } - }, - "/event_based_billing/subscriptions/{subscription_id}/components/{component_id}/deactivate.json": { - "parameters": [ - { - "schema": { - "type": "integer" - }, - "name": "subscription_id", - "in": "path", - "required": true, - "description": "The Chargify id of the subscription" - }, - { - "schema": { - "type": "integer" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "The Chargify id of the component" - } - ], - "post": { - "summary": "Deactivate Event-Based Component", - "tags": [ - "Subscription Components" - ], - "responses": { - "200": { - "description": "OK" - } - }, - "operationId": "deactivateEventBasedComponent", - "description": "Use this endpoint to deactivate an event-based component for a single subscription. Deactivating the event-based component causes Chargify to ignore related events at subscription renewal." - } - }, - "/subscriptions.json": { - "post": { - "summary": "Create Subscription", - "tags": [ - "Subscriptions" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "id": 15236915, - "state": "active", - "balance_in_cents": 0, - "total_revenue_in_cents": 14000, - "product_price_in_cents": 1000, - "product_version_number": 7, - "current_period_ends_at": "2016-11-15T14:48:10-05:00", - "next_assessment_at": "2016-11-15T14:48:10-05:00", - "trial_started_at": null, - "trial_ended_at": null, - "activated_at": "2016-11-14T14:48:12-05:00", - "expires_at": null, - "created_at": "2016-11-14T14:48:10-05:00", - "updated_at": "2016-11-14T15:24:41-05:00", - "cancellation_message": null, - "cancellation_method": "merchant_api", - "cancel_at_end_of_period": null, - "canceled_at": null, - "current_period_started_at": "2016-11-14T14:48:10-05:00", - "previous_state": "active", - "signup_payment_id": 162269766, - "signup_revenue": "260.00", - "delayed_cancel_at": null, - "coupon_code": "5SNN6HFK3GBH", - "payment_collection_method": "automatic", - "snap_day": null, - "reason_code": null, - "receives_invoice_emails": false, - "customer": { - "first_name": "Curtis", - "last_name": "Test", - "email": "curtis@example.com", - "cc_emails": "jeff@example.com", - "organization": "", - "reference": null, - "id": 14714298, - "created_at": "2016-11-14T14:48:10-05:00", - "updated_at": "2016-11-14T14:48:13-05:00", - "address": "123 Anywhere Street", - "address_2": "", - "city": "Boulder", - "state": "CO", - "zip": "80302", - "country": "US", - "phone": "", - "verified": false, - "portal_customer_created_at": "2016-11-14T14:48:13-05:00", - "portal_invite_last_sent_at": "2016-11-14T14:48:13-05:00", - "portal_invite_last_accepted_at": null, - "tax_exempt": false, - "vat_number": "012345678" - }, - "product": { - "id": 3792003, - "name": "$10 Basic Plan", - "handle": "basic", - "description": "lorem ipsum", - "accounting_code": "basic", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "day", - "initial_charge_in_cents": null, - "expiration_interval": null, - "expiration_interval_unit": "never", - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": "month", - "initial_charge_after_trial": false, - "return_params": "", - "request_credit_card": false, - "require_credit_card": false, - "created_at": "2016-03-24T13:38:39-04:00", - "updated_at": "2016-11-03T13:03:05-04:00", - "archived_at": null, - "update_return_url": "", - "update_return_params": "", - "product_family": { - "id": 527890, - "name": "Acme Projects", - "handle": "billing-plans", - "accounting_code": null, - "description": "" - }, - "public_signup_pages": [ - { - "id": 281054, - "url": "https://general-goods.chargify.com/subscribe/kqvmfrbgd89q/basic" - }, - { - "id": 281240, - "url": "https://general-goods.chargify.com/subscribe/dkffht5dxfd8/basic" - }, - { - "id": 282694, - "url": "https://general-goods.chargify.com/subscribe/jwffwgdd95s8/basic" - } - ], - "taxable": false, - "version_number": 7, - "product_price_point_name": "Default" - }, - "credit_card": { - "id": 10191713, - "payment_type": "credit_card", - "first_name": "Curtis", - "last_name": "Test", - "masked_card_number": "XXXX-XXXX-XXXX-1", - "card_type": "bogus", - "expiration_month": 1, - "expiration_year": 2026, - "billing_address": "123 Anywhere Street", - "billing_address_2": "", - "billing_city": "Boulder", - "billing_state": null, - "billing_country": "", - "billing_zip": "80302", - "current_vault": "bogus", - "vault_token": "1", - "customer_vault_token": null, - "customer_id": 14714298 - }, - "payment_type": "credit_card", - "referral_code": "w7kjc9", - "next_product_id": null, - "coupon_use_count": 1, - "coupon_uses_allowed": 1, - "next_product_handle": null, - "stored_credential_transaction_id": 125566112256688, - "dunning_communication_delay_enabled": true, - "dunning_communication_delay_time_zone": "Eastern Time (US & Canada)" - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Bank routing number: cannot be blank.", - "Bank account number: cannot be blank." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createSubscription", - "description": "Full documentation on how subscriptions operate within Chargify can be located under the following topics:\n\n+ [Subscriptions Reference](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405577172749-Subscription-Introduction)\n+ [Subscriptions Actions](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405510556557-Actions)\n+ [Subscription Cancellation](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405510556557-Actions#initiate-cancellation)\n+ [Subscription Reactivation](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404559291021-Reactivating-and-Resuming)\n+ [Subscription Import](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404863655821-Imports)\n\nWhen creating a subscription, you must specify a product and a customer. Credit card details may be required, depending on the options for the Product being subscribed ([see Product Options](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405246782221#payment-method-settings)).\n\nThe product may be specified by `product_id` or by `product_handle` (API Handle). In similar fashion, to pass a particular product price point, you may either use `product_price_point_handle` or `product_price_point_id`.\n\nAn existing customer may be specified by a `customer_id` (ID within Chargify) or a `customer_reference` (unique value within your app that you have shared with Chargify via the reference attribute on a customer). You may also pass in an existing payment profile for that customer with `payment_profile_id`. A new customer may be created by providing `customer_attributes`.\n\nCredit card details may be required, depending on the options for the product being subscribed. The product can be specified by `product_id` or by `product_handle` (API Handle).\n\nIf you are creating a subscription with a payment profile, the attribute to send will be `credit_card_attributes` or `bank_account_attributes` for ACH and Direct Debit. That said, when you read the subscription after creation, we return the profile details under `credit_card` or `bank_account`.\n\n## Taxable Subscriptions\n\nIf your intent is to charge your subscribers tax via [Avalara Taxes](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405275711885-Avalara-VAT-Tax) or [Custom Taxes](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405069041549-Custom-Taxes), there are a few considerations to be made regarding collecting subscription data.\nFor subscribers to be eligible to be taxed, the following information for the `customer` object or `payment_profile` object must by supplied:\n\n+ A subscription to a [taxable product](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405246782221-Product-Editing#tax-settings)\n+ [Full valid billing or shipping address](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405356114317#full-address-required-for-taxable-subscriptions) to identify the tax locale\n+ The portion of the address that houses the [state information](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405356114317#required-state-format-for-taxable-subscriptions) of either adddress must adhere to the ISO standard of a 2-3 character limit/format.\n+ The portion of the address that houses the [country information](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405356114317#required-country-format-for-taxable-subscriptions) must adhere to the ISO standard of a 2 character limit/format.\n\n## Subscription Request Examples\n\nThe subscription examples below will be split into two sections.\n\nThe first section, \"Subscription Customization\", will focus on passing different information with a subscription, such as components, calendar billing, and custom fields. These examples will presume you are using a secure `chargify_token` generated by Chargify.js.\n\nThe second section, \"Passing Payment Information\", will focus on passing payment information into Chargify. Please be aware that collecting and sending Chargify raw card details requires PCI compliance on your end; these examples are provided as guidance. If your business is not PCI compliant, we recommend using Chargify.js to collect credit cards or bank accounts.\n\n# Subscription Customization\n\n## With Components\n\nDifferent components require slightly different data. For example, quantity-based and on/off components accept `allocated_quantity`, while metered components accept `unit_balance`.\n\nWhen creating a subscription with a component, a `price_point_id` can be passed in along with the `component_id` to specify which price point to use. If not passed in, the default price point will be used.\n\nNote: if an invalid `price_point_id` is used, the subscription will still proceed but will use the component's default price point.\n\nComponents and their price points may be added by ID or by handle. See the example request body labeled \"Components By Handle (Quantity-Based)\"; the format will be the same for other component types.\n\n## With Coupon(s)\n\nPass an array of `coupon_codes`. See the example request body \"With Coupon\".\n\n## With Manual Invoice Collection\n\nThe `invoice` collection method works only on legacy Statement Architecture.\n\nOn Relationship Invoicing Architecture use the `remittance` collection method.\n\n## Prepaid Subscription\n\nA prepaid subscription can be created with the usual subscription creation parameters, specifying `prepaid` as the `payment_collection_method` and including a nested `prepaid_configuration`.\n\nAfter a prepaid subscription has been created, additional funds can be manually added to the prepayment account through the [Create Prepayment Endpoint](https://developers.chargify.com/docs/api-docs/7ec482de77ba7-create-prepayment).\n\nPrepaid subscriptions do not work on legacy Statement Architecture.\n\n## With Metafields\n\nMetafields can either attach to subscriptions or customers. Metafields are popuplated with the supplied metadata to the resource specified.\n\nIf the metafield doesn't exist yet, it will be created on-the-fly.\n\n## With Custom Pricing\n\nCustom pricing is pricing specific to the subscription in question.\nCreate a subscription with custom pricing by passing pricing information instead of a price point.\nFor a custom priced product, pass the custom_price object in place of `product_price_point_id`. For a custom priced component, pass the `custom_price` object within the component object.\nCustom prices and price points can exist in harmony on a subscription.\n\n# Passing Payment Information\n\n## Subscription with Chargify.js token\n\nThe `chargify_token` can be obtained using [chargify.js](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDI0-overview). The token represents payment profile attributes that were provided by the customer in their browser and stored at the payment gateway.\n\nThe `payment_type` attribute may either be `credit_card` or `bank_account`, depending on the type of payment method being added. If a bank account is being passed, the payment attributes should be changed to `bank_account_attributes`.\n\n```json\n{\n \"subscription\": {\n \"product_handle\": \"pro-plan\",\n \"customer_attributes\": {\n \"first_name\": \"Joe\",\n \"last_name\": \"Smith\",\n \"email\": \"j.smith@example.com\"\n },\n \"credit_card_attributes\": {\n \"chargify_token\": \"tok_cwhvpfcnbtgkd8nfkzf9dnjn\",\n \"payment_type\": \"credit_card\"\n }\n }\n}\n```\n\n## Subscription with vault token\n\nIf you already have a customer and card stored in your payment gateway, you may create a subscription with a `vault_token`. Providing the last_four, card type and expiration date will allow the card to be displayed properly in the Chargify UI.\n\n```json\n{\n \"subscription\": {\n \"product_handle\": \"pro-plan\",\n \"customer_attributes\": {\n \"first_name\": \"Joe\",\n \"last_name\": \"Smith\",\n \"email\": \"j.smith@example.com\"\n },\n \"credit_card_attributes\": {\n first_name: \"Joe,\n last_name: \"Smith\",\n card_type: \"visa\",\n expiration_month: \"05\",\n expiration_year: \"2025\",\n last_four: \"1234\",\n vault_token: \"12345abc\",\n current_vault: \"braintree_blue\"\n }\n}\n```\n\n## Subscription with Credit Card\n\n```json\n\"subscription\": {\n \"product_handle\": \"basic\",\n \"customer_attributes\": {\n \"first_name\": \"Joe\",\n \"last_name\": \"Blow\",\n \"email\": \"joe@example.com\",\n \"zip\": \"02120\",\n \"state\": \"MA\",\n \"reference\": \"XYZ\",\n \"phone\": \"(617) 111 - 0000\",\n \"organization\": \"Acme\",\n \"country\": \"US\",\n \"city\": \"Boston\",\n \"address_2\": null,\n \"address\": \"123 Mass Ave.\"\n },\n \"credit_card_attributes\": {\n \"last_name\": \"Smith\",\n \"first_name\": \"Joe\",\n \"full_number\": \"4111111111111111\",\n \"expiration_year\": \"2021\",\n \"expiration_month\": \"1\",\n \"card_type\": \"visa\",\n \"billing_zip\": \"02120\",\n \"billing_state\": \"MA\",\n \"billing_country\": \"US\",\n \"billing_city\": \"Boston\",\n \"billing_address_2\": null,\n \"billing_address\": \"123 Mass Ave.\"\n }\n}\n```\n\n## Subscription with ACH as Payment Profile\n\n```json\n{\n \"subscription\": {\n \"product_handle\": \"gold-product\",\n \"customer_attributes\": {\n \"first_name\": \"Joe\",\n \"last_name\": \"Blow\",\n \"email\": \"joe@example.com\",\n \"zip\": \"02120\",\n \"state\": \"MA\",\n \"reference\": \"XYZ\",\n \"phone\": \"(617) 111 - 0000\",\n \"organization\": \"Acme\",\n \"country\": \"US\",\n \"city\": \"Boston\",\n \"address_2\": null,\n \"address\": \"123 Mass Ave.\"\n },\n \"bank_account_attributes\": {\n \"bank_name\": \"Best Bank\",\n \"bank_routing_number\": \"021000089\",\n \"bank_account_number\": \"111111111111\",\n \"bank_account_type\": \"checking\",\n \"bank_account_holder_type\": \"business\",\n \"payment_type\": \"bank_account\"\n }\n }\n}\n```\n\n## Subscription with PayPal payment profile\n\n### With the nonce from Braintree JS\n\n```json\n{ \"subscription\": {\n \"product_handle\":\"test-product-b\",\n \"customer_attributes\": {\n \"first_name\":\"Amelia\",\n \"last_name\":\"Johnson\",\n \"email\":\"amelia@example.com\",\n \"organization\":\"My Awesome Company\"\n },\n \"payment_profile_attributes\":{\n \"paypal_email\": \"amelia@example.com\",\n \"current_vault\": \"braintree_blue\",\n \"payment_method_nonce\":\"abc123\",\n \"payment_type\":\"paypal_account\"\n }\n }\n```\n\n\n### With the Braintree Customer ID as the vault token:\n\n```json\n{ \"subscription\": {\n \"product_handle\":\"test-product-b\",\n \"customer_attributes\": {\n \"first_name\":\"Amelia\",\n \"last_name\":\"Johnson\",\n \"email\":\"amelia@example.com\",\n \"organization\":\"My Awesome Company\"\n },\n \"payment_profile_attributes\":{\n \"paypal_email\": \"amelia@example.com\",\n \"current_vault\": \"braintree_blue\",\n \"vault_token\":\"58271347\",\n \"payment_type\":\"paypal_account\"\n }\n }\n```\n\n## Subscription using GoCardless Bank Number\n\nThese examples creates a customer, bank account and mandate in GoCardless.\n\nFor more information on GoCardless, please view the following two resources:\n\n+ [Payment Profiles via API for GoCardless](https://developers.chargify.com/docs/api-docs/1f10a4f170405-create-payment-profile#gocardless)\n+ [Full documentation on GoCardless](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404501889677)\n\n+ [Using Chargify.js with GoCardless - minimal example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#minimal-example-with-direct-debit-gocardless-gateway)\n\n+ [Using Chargify.js with GoCardless - full example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#full-example-with-direct-debit-gocardless-gateway)\n\n```json\n{\n \"subscription\": {\n \"product_handle\": \"gold-product\",\n \"customer_attributes\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"email\": \"jd@chargify.test\"\n },\n \"bank_account_attributes\": {\n \"bank_name\": \"Royal Bank of France\",\n \"bank_account_number\": \"0000000\",\n \"bank_routing_number\": \"0003\",\n \"bank_branch_code\": \"00006\",\n \"payment_type\": \"bank_account\",\n \"billing_address\": \"20 Place de la Gare\",\n \"billing_city\": \"Colombes\",\n \"billing_state\": \"Île-de-France\",\n \"billing_zip\": \"92700\",\n \"billing_country\": \"FR\"\n }\n }\n}\n```\n\n## Subscription using GoCardless IBAN Number\n\n```json\n{\n \"subscription\": {\n \"product_handle\": \"gold-product\",\n \"customer_attributes\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"email\": \"jd@chargify.test\"\n },\n \"bank_account_attributes\": {\n \"bank_name\": \"French Bank\",\n \"bank_iban\": \"FR1420041010050500013M02606\",\n \"payment_type\": \"bank_account\",\n \"billing_address\": \"20 Place de la Gare\",\n \"billing_city\": \"Colombes\",\n \"billing_state\": \"Île-de-France\",\n \"billing_zip\": \"92700\",\n \"billing_country\": \"FR\"\n }\n }\n}\n```\n\n## Subscription using Stripe SEPA Direct Debit\n\nFor more information on Stripe Direct Debit, please view the following two resources:\n\n+ [Payment Profiles via API for Stripe SEPA Direct Debit](https://developers.chargify.com/docs/api-docs/1f10a4f170405-create-payment-profile#sepa-direct-debit)\n+ [Full documentation on Stripe Direct Debit](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405050826765-Stripe-SEPA-and-BECS-Direct-Debit)\n\n+ [Using Chargify.js with Stripe SEPA or BECS Direct Debit - minimal example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#minimal-example-with-sepa-or-becs-direct-debit-stripe-gateway)\n\n+ [Using Chargify.js with Stripe SEPA Direct Debit - full example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#full-example-with-sepa-direct-debit-stripe-gateway)\n\n\n```json\n{\n \"subscription\": {\n \"product_handle\": \"gold-product\",\n \"customer_attributes\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"email\": \"jd@chargify.test\"\n },\n \"bank_account_attributes\": {\n \"bank_name\": \"Test Bank\",\n \"bank_iban\": \"DE89370400440532013000\",\n \"payment_type\": \"bank_account\"\n }\n }\n}\n```\n\n## Subscription using Stripe BECS Direct Debit\n\nFor more information on Stripe Direct Debit, please view the following two resources:\n\n+ [Payment Profiles via API for Stripe BECS Direct Debit](https://developers.chargify.com/docs/api-docs/1f10a4f170405-create-payment-profile#stripe-becs-direct-debit)\n+ [Full documentation on Stripe Direct Debit](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405050826765-Stripe-SEPA-and-BECS-Direct-Debit)\n\n+ [Using Chargify.js with Stripe SEPA or BECS Direct Debit - minimal example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#minimal-example-with-sepa-or-becs-direct-debit-stripe-gateway)\n\n+ [Using Chargify.js with Stripe BECS Direct Debit - full example](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDIy-examples#full-example-with-becs-direct-debit-stripe-gateway)\n\n\n```json\n{\n \"subscription\": {\n \"product_handle\": \"gold-product\",\n \"customer_attributes\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"email\": \"jd@chargify.test\"\n },\n \"bank_account_attributes\": {\n \"bank_name\": \"Test Bank\",\n \"bank_branch_code\": \"000000\",\n \"bank_account_number\": \"000123456\",\n \"payment_type\": \"bank_account\"\n }\n }\n}\n```\n\n## 3D Secure - Stripe\n\nIt may happen that a payment needs 3D Secure Authentication when the subscription is created; this is referred to in our help docs as a [post-authentication flow](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405177432077#psd2-flows-pre-authentication-and-post-authentication). The server returns `422 Unprocessable Entity` in this case with the following response:\n\n```json\n{\n \"errors\": [\n \"Your card was declined. This transaction requires 3D secure authentication.\"\n ],\n \"gateway_payment_id\": \"pi_1F0aGoJ2UDb3Q4av7zU3sHPh\",\n \"description\": \"This card requires 3D secure authentication. Redirect the customer to the URL from the action_link attribute to authenticate. Attach callback_url param to this URL if you want to be notified about the result of 3D Secure authentication. Attach redirect_url param to this URL if you want to redirect a customer back to your page after 3D Secure authentication. Example: https://mysite.chargify.com/3d-secure/pi_1FCm4RKDeye4C0XfbqquXRYm?one_time_token_id=128&callback_url=https://localhost:4000&redirect_url=https://yourpage.com will do a POST request to https://localhost:4000 after payment is authenticated and will redirect a customer to https://yourpage.com after 3DS authentication.\",\n \"action_link\": \"http://acme.chargify.com/3d-secure/pi_1F0aGoJ2UDb3Q4av7zU3sHPh?one_time_token_id=242\"\n}\n```\n\nTo let the customer go through 3D Secure Authentication, they need to be redirected to the URL specified in `action_link`.\nOptionally, you can specify `callback_url` parameter in the `action_link` URL if you’d like to be notified about the result of 3D Secure Authentication. The `callback_url` will return the following information:\n\n- whether the authentication was successful (`success`)\n- the gateway ID for the payment (`gateway_payment_id`)\n- the subscription ID (`subscription_id`)\n\nLastly, you can also specify a `redirect_url` within the `action_link` URL if you’d like to redirect a customer back to your site.\n\nIt is not possible to use `action_link` in an iframe inside a custom application. You have to redirect the customer directly to the `action_link`, then, to be notified about the result, use `redirect_url` or `callback_url`.\n\nThe final URL that you send a customer to to complete 3D Secure may resemble the following, where the first half is the `action_link` and the second half contains a `redirect_url` and `callback_url`: `https://mysite.chargify.com/3d-secure/pi_1FCm4RKDeye4C0XfbqquXRYm?one_time_token_id=128&callback_url=https://localhost:4000&redirect_url=https://yourpage.com`\n\n## 3D Secure - Checkout\n\nIt may happen that a payment needs 3D Secure Authentication when the subscription is created; this is referred to in our help docs as a [post-authentication flow](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405177432077#psd2-flows-pre-authentication-and-post-authentication). The server returns `422 Unprocessable Entity` in this case with the following response:\n\n```json\n{\n \"errors\": [\n \"Your card was declined. This transaction requires 3D secure authentication.\"\n ],\n \"gateway_payment_id\": \"pay_6gjofv7dlyrkpizlolsuspvtiu\",\n \"description\": \"This card requires 3D secure authentication. Redirect the customer to the URL from the action_link attribute to authenticate. Attach callback_url param to this URL if you want to be notified about the result of 3D Secure authentication. Attach redirect_url param to this URL if you want to redirect a customer back to your page after 3D Secure authentication. Example: https://mysite.chargify.com/3d-secure/pay_6gjofv7dlyrkpizlolsuspvtiu?one_time_token_id=123&callback_url=https://localhost:4000&redirect_url=https://yourpage.com will do a POST request to https://localhost:4000 after payment is authenticated and will redirect a customer to https://yourpage.com after 3DS authentication.\",\n \"action_link\": \"http://mysite.chargify.com/3d-secure/pay_6gjofv7dlyrkpizlolsuspvtiu?one_time_token_id=123\"\n}\n```\n\nTo let the customer go through 3D Secure Authentication, they need to be redirected to the URL specified in `action_link`.\nOptionally, you can specify `callback_url` parameter in the `action_link` URL if you’d like to be notified about the result of 3D Secure Authentication. The `callback_url` will return the following information:\n\n- whether the authentication was successful (`success`)\n- the gateway ID for the payment (`gateway_payment_id`)\n- the subscription ID (`subscription_id`)\n\nLastly, you can also specify a `redirect_url` parameter within the `action_link` URL if you’d like to redirect a customer back to your site.\n\nIt is not possible to use `action_link` in an iframe inside a custom application. You have to redirect the customer directly to the `action_link`, then, to be notified about the result, use `redirect_url` or `callback_url`.\n\nThe final URL that you send a customer to complete 3D Secure may resemble the following, where the first half is the `action_link` and the second half contains a `redirect_url` and `callback_url`: `https://mysite.chargify.com/3d-secure/pay_6gjofv7dlyrkpizlolsuspvtiu?one_time_token_id=123&callback_url=https://localhost:4000&redirect_url=https://yourpage.com`\n\n### Example Redirect Flow\n\nYou may wish to redirect customers to different pages depending on whether their SCA was performed successfully. Here's an example flow to use as a reference:\n\n1. Create a subscription via API; it requires 3DS\n2. You receive a `gateway_payment_id` in the `action_link` along other params in the response.\n3. Use this `gateway_payment_id` to, for example, connect with your internal resources or generate a session_id\n4. Include 1 of those attributes inside the `callback_url` and `redirect_url` to be aware which “session” this applies to\n5. Redirect the customer to the `action_link` with `callback_url` and `redirect_url` applied\n6. After the customer finishes 3DS authentication, we let you know the result by making a request to applied `callback_url`.\n7. After that, we redirect the customer to the `redirect_url`; at this point the result of authentication is known\n8. Optionally, you can use the applied \"msg\" param in the `redirect_url` to determine whether it was successful or not\n\n## Subscriptions Import\n\nSubscriptions can be “imported” via the API to handle the following scenarios:\n\n+ You already have existing subscriptions with specific start and renewal dates that you would like to import to Chargify\n+ You already have credit cards stored in your provider’s vault and you would like to create subscriptions using those tokens\n\nBefore importing, you should have already set up your products to match your offerings. Then, you can create Subscriptions via the API just like you normally would, but using a few special attributes.\n\nFull documentation on how import Subscriptions using the **import tool** in the Chargify UI can be located [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404863655821#imports-0-0).\n\n### Important Notices and Disclaimers regarding Imports\n\nBefore performing a bulk import of subscriptions via the API, we suggest reading the [Subscriptions Import](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404863655821#important-notices-and-disclaimers) instructions to understand the repurcussions of a large import.\n\n### Subscription Input Attributes\n\nThe following _additional_ attributes to the subscription input attributes make imports possible: `next_billing_at`, `previous_billing_at`, and `import_mrr`.\n\n### Current Vault\n\nIf you are using a Legacy gateway such as \"eWAY Rapid (Legacy)\" or \"Stripe (Legacy)\" then please contact Support for further instructions on subscription imports.\n\n### Braintree Blue (Braintree v2) Imports\n\nBraintree Blue is Braintree’s newer (version 2) API. For this gateway, please provide the `vault_token` parameter with the value from Braintree’s “Customer ID” rather than the “Payment Profile Token”. At this time we do not use `current_vault_token` with the Braintree Blue gateway, and we only support a single payment profile per Braintree Customer.\n\nWhen importing PayPal type payment profiles, please set `payment_type` to `paypal_account`.\n\n### Stripe ACH Imports\n\nIf the bank account has already been verified, currently you will need to create the customer, create the payment profile in Chargify - setting verified=true, then create a subscription using the customer_id and payment_profile_id.\n\n### Webhooks During Import\n\nIf no `next_billing_at` is provided, webhooks will be fired as normal. If you do set a future `next_billing_at`, only a subset of the webhooks are fired when the subscription is created. Keep reading for more information as to what webhooks will be fired under which scenarios.\n\n#### Successful creation with Billing Date\n\nScenario: If `next_billing_at` provided\n\n+ `signup_success`\n+ `billing_date_change`\n\n#### Successful creation without Billing Date\n\nScenario: If no `next_billing_at` provided\n\n+ `signup_success`\n+ `payment_success`\n\n#### Unsuccessful creation\n\nScenario: If card can’t be charged, and no `next_billing_at` provided\n\n+ signup_failure\n\n#### Webhooks fired when next_billing_at is reached:\n\n+ `renewal_success or renewal_failure`\n+ `payment_success or payment_failure`\n\n### Date and Time Formats\n\nWe will attempt to parse any string you send as the value of next_billing_at in to a date or time. For best results, use a known format like described in “Date and Time Specification” of RFC 2822 or ISO 8601 .\n\nThe following are all equivalent and will work as input to `next_billing_at`:\n\n```\nAug 06 2030 11:34:00 -0400\nAug 06 2030 11:34 -0400\n2030-08-06T11:34:00-04:00\n8/6/2030 11:34:00 EDT\n8/6/2030 8:34:00 PDT\n2030-08-06T15:34:00Z\n```\nYou may also pass just a date, in which case we will assume the time to be noon\n\n```\n2010-08-06\n```\n\n## Subscription Hierarchies & WhoPays\n\nWhen subscription groups were first added to our Relationship Invoicing architecture, to group together invoices for related subscriptions and allow for complex customer hierarchies and WhoPays scenarios, they were designed to consist of a primary and a collection of group members. The primary would control many aspects of the group, such as when the consolidated invoice is generated. As of today, groups still function this way.\n\nIn the future, the concept of a \"primary\" will be removed in order to offer more flexibility into group management and reduce confusion concerning what actions must be done on a primary level, rather than a member level.\n\nWe have introduced a two scheme system as a bridge between these two group organizations. Scheme 1, which is relevant to all subscription groups today, marks the group as being \"ruled\" by a primary.\n\nWhen reading a subscription via API, they will return a top-level attribute called `group`, which will denote which scheme is being used. At this time, the `scheme` attribute will always be 1.\n\n### Subscription in a Customer Hierarchy\n\nFor sites making use of the [Relationship Billing](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405078794253-Introduction-to-Invoices) and [Customer Hierarchy](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404900384141) features, it is possible to create subscriptions within a customer hierarchy. This can be achieved through the API by passing group parameters in the **Create Subscription** request.\n\n+ The `group` parameters are optional and consist of the required `target` and optional `billing` parameters.\n\nWhen the `target` parameter specifies a customer that is already part of a hierarchy, the new subscription will become a member of the customer hierarchy as well. If the target customer is not part of a hierarchy, a new customer hierarchy will be created and both the target customer and the new subscription will become part of the hierarchy with the specified target customer set as the responsible payer for the hierarchy's subscriptions.\n\nRather than specifying a customer, the `target` parameter could instead simply have a value of `self` which indicates the subscription will be paid for not by some other customer, but by the subscribing customer. This will be true whether the customer is being created new, is already part of a hierarchy, or already exists outside a hierarchy. A valid payment method must also be specified in the subscription parameters.\n\nNote that when creating subscriptions in a customer hierarchy, if the customer hierarchy does not already have a payment method, passing valid credit card attributes in the subscription parameters will also result in the payment method being established as the default payment method for the customer hierarchy irrespective of the responsible payer.\n\nThe optional `billing` parameters specify how some aspects of the billing for the new subscription should be handled. Rather than capturing payment immediately, the `accrue` parameter can be included so that the new subscription charges accrue until the next assessment date. Regarding the date, the `align_date` parameter can be included so that the billing date of the new subscription matches up with the default subscription group in the customer hierarchy. When choosing to align the dates, the `prorate` parameter can also be specified so that the new subscription charges are prorated based on the billing period of the default subscription group in the customer hierarchy also.\n\n### Subscription in a Subscription Group\n\nFor sites making use of [Relationship Billing](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405078794253-Introduction-to-Invoices) it may be desireable to create a subscription as part of a [subscription group](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405577356173) in order to rely on [invoice consolidation](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404980119949). This can be achieved through the API by passing group parameters in the Create Subscription request. The `group` parameters are optional and consist of the required `target` and optional `billing` parameters.\n\nThe `target` parameters specify an existing subscription with which the newly created subscription should be grouped. If the target subscription is already part of a group, the new subscription will become a member of the group as well. If the target subscription is not part of a group, a new group will be created and both the target and the new subscription will become part of the group with the target as the group's primary subscription.\n\nThe optional `billing` parameters specify how some aspects of the billing for the new subscription should be handled. Rather than capturing payment immediately, the `accrue` parameter can be included so that the new subscription charges accrue until the next assessment date. Regarding the date, the `align_date` parameter can be included so that the billing date of the new subscription matches up with the target subscription. When choosing to align the dates, the `prorate` parameter can also be specified so that the new subscription charges are prorated based on the billing period of the target subscription also.\n\n## Providing Agreement Acceptance Params\n\nIt is possible to provide a proof of customer's acceptance of terms and policies.\nWe will be storing this proof in case it might be required (i.e. chargeback).\nCurrently, we already keep it for subscriptions created via Public Signup Pages.\nIn order to create a subscription with the proof of agreement acceptance, you must provide additional parameters `agreement acceptance` with `ip_address` and at least one url to the policy that was accepted: `terms_url` or `privacy_policy_url`. Additional urls that can be provided: `return_refund_policy_url`, `delivery_policy_url` and\n`secure_checkout_policy_url`.\n\n```json\n \"subscription\": {\n \"product_handle\": \"gold-product\",\n \"customer_attributes\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"email\": \"jd@chargify.test\"\n },\n \"agreement_acceptance\": {\n \"ip_address\": \"1.2.3.4\",\n \"terms_url\": \"https://terms.url\",\n \"privacy_policy_url\": \"https://privacy_policy.url\",\n \"return_refund_policy_url\": \"https://return_refund_policy.url\",\n \"delivery_policy_url\": \"https://delivery_policy.url\",\n \"secure_checkout_policy_url\": \"https://secure_checkout_policy.url\"\n }\n }\n}\n```\n\n**For Maxio Payments subscriptions, the agreement acceptance params are required, with at least terms_url provided.**\n\n## Providing ACH Agreement params\n\nIt is also possible to provide a proof that a customer authorized ACH agreement terms.\nThe proof will be stored and the email will be sent to the customer with a copy of the terms (if enabled).\nIn order to create a subscription with the proof of authorized ACH agreement terms, you must provide the additional parameter `ach_agreement` with the following nested parameters: `agreement_terms`, `authorizer_first_name`, `authorizer_last_name` and `ip_address`.\nEach of them is required.\n\n```json\n \"subscription\": {\n \"product_handle\": \"gold-product\",\n \"customer_attributes\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"email\": \"jd@chargify.test\"\n },\n \"bank_account_attributes\": {\n \"bank_name\": \"Test Bank\",\n \"bank_routing_number\": \"021000089\",\n \"bank_account_number\": \"111111111111\",\n \"bank_account_type\": \"checking\",\n \"bank_account_holder_type\": \"business\",\n \"payment_type\": \"bank_account\"\n },\n \"ach_agreement\": {\n \"agreement_terms\": \"ACH agreement terms\",\n \"authorizer_first_name\": \"Jane\",\n \"authorizer_last_name\": \"Doe\",\n \"ip_address\": \"1.2.3.4\"\n }\n }\n```", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Subscription-Request.yaml" - }, - "examples": { - "Basic": { - "value": { - "subscription": { - "product_handle": "basic", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Blow", - "email": "joe@example.com", - "zip": "02120", - "state": "MA", - "reference": "XYZ", - "phone": "(617) 111 - 0000", - "organization": "Acme", - "country": "US", - "city": "Boston", - "address_2": null, - "address": "123 Mass Ave." - }, - "credit_card_attributes": { - "last_name": "Smith", - "first_name": "Joe", - "full_number": "4111111111111111", - "expiration_year": "2021", - "expiration_month": "1", - "card_type": "visa", - "billing_zip": "02120", - "billing_state": "MA", - "billing_country": "US", - "billing_city": "Boston", - "billing_address_2": null, - "billing_address": "123 Mass Ave." - } - } - } - }, - "Calendar Billing": { - "value": { - "subscription": { - "product_handle": "gold", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Blow", - "email": "joe@example.com", - "zip": "02120", - "state": "MA", - "reference": "XYZ", - "phone": "(617) 111 - 0000", - "organization": "Acme", - "country": "US", - "city": "Boston", - "address_2": null, - "address": "123 Mass Ave." - }, - "calendar_billing": { - "snap_day": 1, - "calendar_billing_first_charge": "immediate" - }, - "credit_card_attributes": { - "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn" - } - } - } - }, - "Components (Metered)": { - "value": { - "subscription": { - "product_handle": "basic", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Blow", - "email": "joe1049am@example.com" - }, - "credit_card_attributes": { - "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn" - }, - "components": [ - { - "component_id": 195268, - "unit_balance": 20 - } - ] - } - } - }, - "Components (On/Off)": { - "value": { - "subscription": { - "product_handle": "basic", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Blow", - "email": "joe@example.com" - }, - "credit_card_attributes": { - "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn" - }, - "components": [ - { - "component_id": 2500, - "enabled": true - } - ] - } - } - }, - "Components (Quantity-Based)": { - "value": { - "subscription": { - "product_handle": "basic", - "customer_attributes": { - "first_name": "Alysa", - "last_name": "Test", - "email": "alysa@example.com" - }, - "credit_card_attributes": { - "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn" - }, - "components": [ - { - "component_id": 1, - "allocated_quantity": 18, - "price_point_id": 3 - } - ] - } - } - }, - "Components By Handle (Quantity-Based)": { - "value": { - "subscription": { - "product_handle": "basic", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Blow", - "email": "joe@example.com" - }, - "credit_card_attributes": { - "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn" - }, - "components": [ - { - "component_id": "handle:my-handle", - "price_point_id": "handle:special-offer", - "allocated_quantity": 14 - } - ] - } - } - }, - "With Coupon": { - "value": { - "subscription": { - "product_handle": "basic", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Blow", - "email": "joe@example.com" - }, - "credit_card_attributes": { - "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn" - }, - "coupon_code": "SUB111" - } - } - }, - "Grouped": { - "value": { - "subscription": { - "product_handle": "product-xyz", - "customer_id": 43693465, - "payment_profile_id": 74404848, - "group": { - "target": { - "type": "customer", - "id": 43693465 - }, - "billing": { - "align_date": true, - "prorate": false, - "accrue": false - } - } - } - } - }, - "In Hierarchy (not Group)": { - "value": { - "subscription": { - "product_handle": "test_product", - "customer_attributes": { - "first_name": "Child who pays for self", - "last_name": "(No subscription group)", - "email": "joe@example.com", - "parent_id": 23554144 - } - } - } - }, - "Import as Canceled": { - "value": { - "subscription": { - "product_handle": "product", - "canceled_at": "2021-02-25T12:00:00-04:00", - "cancellation_message": "Too expensive", - "reason_code": "expensive", - "activated_at": "2021-01-17T12:00:00-04:00", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Test", - "email": "joetest@example.com" - }, - "bank_account_attributes": { - "bank_name": "My Bank", - "current_vault": "stripe_connect", - "vault_token": "1234" - } - } - } - }, - "Import With Future Billing Date": { - "value": { - "subscription": { - "product_handle": "basic", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Blow", - "email": "joe@example.com" - }, - "credit_card_attributes": { - "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn" - }, - "next_billing_at": "2020-06-01T12:00:00-04:00" - } - } - }, - "Import Authorize.Net ACH": { - "value": { - "subscription": { - "product_handle": "product", - "next_billing_at": "2020-08-29T12:00:00-04:00", - "customer_attributes": { - "first_name": "John", - "last_name": "Doe", - "email": "john.doe@example.com" - }, - "bank_account_attributes": { - "bank_name": "My Bank", - "current_vault": "authorizenet", - "vault_token": "1234", - "customer_vault_token": "5678" - } - } - } - }, - "Import Stripe ACH": { - "value": { - "subscription": { - "product_handle": "product", - "next_billing_at": "2020-08-29T12:00:00-04:00", - "customer_attributes": { - "first_name": "John", - "last_name": "Doe", - "email": "john.doe@example.com" - }, - "bank_account_attributes": { - "bank_name": "My Bank", - "current_vault": "stripe_connect", - "vault_token": "cus_abc123" - } - } - } - }, - "Metadata (Subscription-Level)": { - "value": { - "subscription": { - "product_handle": "basic", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Blow", - "email": "joe@example.com" - }, - "credit_card_attributes": { - "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn" - }, - "metafields": { - "color": "blue", - "comments": "Thanks!" - } - } - } - }, - "Metadata (Customer-Level)": { - "value": { - "subscription": { - "product_handle": "basic", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Blow", - "email": "joe@example.com", - "metafields": { - "nickname": "Boris", - "language": "Spanish" - } - }, - "credit_card_attributes": { - "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn" - } - } - } - }, - "With Offer": { - "value": { - "subscription": { - "offer_id": "handle:godfather", - "customer_attributes": { - "first_name": "Alysa", - "last_name": "Test", - "email": "alysa@example.com" - }, - "credit_card_attributes": { - "full_number": "1", - "expiration_month": "10", - "expiration_year": "2020" - } - } - } - }, - "Prepaid Subscription": { - "value": { - "subscription": { - "product_handle": "basic", - "customer_id": 12345, - "payment_profile_id": 6789, - "payment_collection_method": "prepaid", - "prepaid_configuration": { - "initial_funding_amount_in_cents": 10000, - "replenish_to_amount_in_cents": 6000, - "auto_replenish": true, - "replenish_threshold_amount_in_cents": 5000 - } - } - } - }, - "With Referral Code": { - "value": { - "subscription": { - "product_handle": "product-handle", - "ref": "1q2w3e", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Blow", - "email": "joe@example.com" - }, - "credit_card_attributes": { - "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn" - } - } - } - }, - "With Custom Pricing": { - "value": { - "subscription": { - "product_id": 123, - "custom_price": { - "handle": "custom-price", - "price_in_cents": 9900, - "interval": 1, - "interval_unit": "month" - }, - "components": [ - { - "component_id": 20, - "allocated_quantity": 10, - "custom_price": { - "pricing_scheme": "stairstep", - "prices": [ - { - "unit_price": 5, - "starting_quantity": 1, - "ending_quantity": 15 - }, - { - "unit_price": 2, - "starting_quantity": 16 - } - ] - } - }, - { - "component_id": 10, - "enabled": true, - "custom_price": { - "prices": [ - { - "unit_price": 1, - "starting_quantity": 1 - } - ] - } - } - ] - } - } - }, - "With Agreement Acceptance": { - "value": { - "subscription": { - "product_handle": "basic", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Blow", - "email": "joe@example.com" - }, - "credit_card_attributes": { - "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn" - }, - "agreement_acceptance": { - "ip_address": "1.2.3.4", - "terms_url": "https://terms.url", - "privacy_policy_url": "https://privacy_policy.url", - "return_refund_policy_url": "https://return_refund_policy.url", - "delivery_policy_url": "https://delivery_policy_.url", - "secure_checkout_policy_url": "https://secure_checkout_policy.url" - } - } - } - }, - "With ACH Agreement": { - "value": { - "subscription": { - "product_handle": "basic", - "customer_attributes": { - "first_name": "Joe", - "last_name": "Blow", - "email": "joe@example.com" - }, - "bank_account_attributes": { - "bank_name": "Test Bank", - "bank_routing_number": "021000089", - "bank_account_number": "111111111111", - "bank_account_type": "checking", - "bank_account_holder_type": "business", - "payment_type": "bank_account" - }, - "ach_agreement": { - "agreement_terms": "ACH agreement terms", - "authorizer_first_name": "Jane", - "authorizer_last_name": "Doe", - "ip_address": "1.2.3.4" - } - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Subscriptions", - "tags": [ - "Subscriptions" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Subscription-Response.yaml" - } - } - } - } - } - }, - "operationId": "listSubscriptions", - "x-operation-settings": { - "collectParameters": true - }, - "description": "This method will return an array of subscriptions from a Site. Pay close attention to query string filters and pagination in order to control responses from the server.\n\n## Search for a subscription\n\nUse the query strings below to search for a subscription using the criteria available. The return value will be an array.\n\n## Self-Service Page token\n\nSelf-Service Page token for the subscriptions is not returned by default. If this information is desired, the include[]=self_service_page_token parameter must be provided with the request.", - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "name": "state", - "in": "query", - "schema": { - "$ref": "../components/schemas/Subscription-State-Filter.yaml" - }, - "description": "The current state of the subscription" - }, - { - "name": "product", - "in": "query", - "schema": { - "type": "integer" - }, - "description": "The product id of the subscription. (Note that the product handle cannot be used.)" - }, - { - "name": "product_price_point_id", - "in": "query", - "schema": { - "type": "integer" - }, - "description": "The ID of the product price point. If supplied, product is required" - }, - { - "name": "coupon", - "in": "query", - "schema": { - "type": "integer" - }, - "description": "The numeric id of the coupon currently applied to the subscription. (This can be found in the URL when editing a coupon. Note that the coupon code cannot be used.)" - }, - { - "name": "date_field", - "in": "query", - "schema": { - "$ref": "../components/schemas/Subscription-Date-Field.yaml" - }, - "description": "The type of filter you'd like to apply to your search. Allowed Values: , current_period_ends_at, current_period_starts_at, created_at, activated_at, canceled_at, expires_at, trial_started_at, trial_ended_at, updated_at" - }, - { - "name": "start_date", - "in": "query", - "schema": { - "type": "string", - "format": "date" - }, - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. Use in query `start_date=2022-07-01`.", - "example": "2022-07-01" - }, - { - "name": "end_date", - "in": "query", - "schema": { - "type": "string", - "format": "date" - }, - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. Use in query `end_date=2022-08-01`.", - "example": "2022-08-01" - }, - { - "name": "start_datetime", - "in": "query", - "schema": { - "type": "string", - "format": "date-time" - }, - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. Use in query `start_datetime=2022-07-01 09:00:05`.", - "example": "2022-07-01 09:00:05" - }, - { - "name": "end_datetime", - "in": "query", - "schema": { - "type": "string", - "format": "date-time" - }, - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. Use in query `end_datetime=2022-08-01 10:00:05`.", - "example": "2022-08-01 10:00:05" - }, - { - "name": "metadata", - "in": "query", - "schema": { - "allOf": [ - { - "$ref": "../components/schemas/Metafields-Values.yaml" - } - ], - "description": "A set of key/value pairs representing custom fields and their values." - }, - "style": "deepObject", - "explode": true, - "description": "The value of the metadata field specified in the parameter. Use in query `metadata[my-field]=value&metadata[other-field]=another_value`." - }, - { - "$ref": "../components/parameters/sort-direction.yaml" - }, - { - "schema": { - "$ref": "../components/schemas/Subscription-Sort.yaml" - }, - "in": "query", - "name": "sort", - "description": "The attribute by which to sort" - }, - { - "name": "include[]", - "in": "query", - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Subscription-List-Include.yaml" - }, - "example": [ - "self_service_page_token" - ] - }, - "style": "form", - "explode": true, - "description": "Allows including additional data in the response. Use in query: `include[]=self_service_page_token`." - } - ] - } - }, - "/{subdomain}/events/{api_handle}.json": { - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "subdomain", - "in": "path", - "required": true, - "description": "Your site's subdomain" - }, - { - "schema": { - "type": "string" - }, - "name": "api_handle", - "in": "path", - "required": true, - "description": "Identifies the Stream for which the event should be published." - } - ], - "post": { - "summary": "Event Ingestion", - "tags": [ - "Subscription Components" - ], - "responses": { - "201": { - "description": "Created" - } - }, - "operationId": "recordEvent", - "description": "## Documentation\n\nEvents-Based Billing is an evolved form of metered billing that is based on data-rich events streamed in real-time from your system to Chargify.\n\nThese events can then be transformed, enriched, or analyzed to form the computed totals of usage charges billed to your customers.\n\nThis API allows you to stream events into the Chargify data ingestion engine.\n\nLearn more about the feature in general in the [Events-Based Billing help docs](https://chargify.zendesk.com/hc/en-us/articles/4407720613403).\n\n## Record Event\n\nUse this endpoint to record a single event.\n\n*Note: this endpoint differs from the standard Chargify endpoints in that the URL subdomain will be `events` and your site subdomain will be included in the URL path. For example:*\n\n```\nhttps://events.chargify.com/my-site-subdomain/events/my-stream-api-handle\n```", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "store_uid", - "description": "If you've attached your own Keen project as a Chargify event data-store, use this parameter to indicate the data-store." - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Ebb-Event.yaml" - }, - "examples": { - "Example": { - "value": { - "chargify": { - "subscription_id": 1, - "timestamp": "2020-02-27T17:45:50-05:00" - }, - "messages": 150, - "country": "US", - "customer": { - "name": "John", - "lastName": "Doe", - "address": { - "street": "Maple Street", - "zip": 4888, - "state": "MA" - } - } - } - } - } - } - } - } - }, - "servers": [ - { - "url": "https://events.chargify.com", - "description": "Production server" - } - ] - }, - "/{subdomain}/events/{api_handle}/bulk.json": { - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "subdomain", - "in": "path", - "required": true, - "description": "Your site's subdomain" - }, - { - "schema": { - "type": "string" - }, - "name": "api_handle", - "in": "path", - "required": true, - "description": "Identifies the Stream for which the events should be published." - } - ], - "post": { - "summary": "Bulk Event Ingestion", - "tags": [ - "Subscription Components" - ], - "responses": { - "201": { - "description": "Created" - } - }, - "operationId": "bulkRecordEvents", - "description": "Use this endpoint to record a collection of events.\n\n*Note: this endpoint differs from the standard Chargify endpoints in that the subdomain will be `events` and your site subdomain will be included in the URL path.*\n\nA maximum of 1000 events can be published in a single request. A 422 will be returned if this limit is exceeded.", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "store_uid", - "description": "If you've attached your own Keen project as a Chargify event data-store, use this parameter to indicate the data-store." - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Ebb-Event.yaml" - } - } - } - } - } - }, - "servers": [ - { - "url": "https://events.chargify.com", - "description": "Production server" - } - ] - }, - "/offers.json": { - "post": { - "summary": "Create Offer", - "tags": [ - "Offers" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Offer-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "offer": { - "id": 3, - "site_id": 2, - "product_family_id": 4, - "product_family_name": "Chargify", - "product_id": 31, - "product_name": "30-Day Square Trial", - "product_price_in_cents": 2000, - "product_revisable_number": 0, - "name": "Solo", - "handle": "han_shot_first", - "description": "A Star Wars Story", - "created_at": "2018-06-08T14:51:52-04:00", - "updated_at": "2018-06-08T14:51:52-04:00", - "archived_at": null, - "product_price_point_name": "Default", - "offer_items": [ - { - "component_id": 24, - "component_name": "Invoices", - "component_unit_price": "3.0", - "price_point_id": 104, - "price_point_name": "Original", - "starting_quantity": "1.0", - "editable": false - } - ], - "offer_discounts": [ - { - "coupon_id": 3, - "coupon_code": "DEF456", - "coupon_name": "IB Loyalty" - } - ] - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-Array-Map-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": { - "components": [ - "starting_quantity for an On/Off component can only be '1' or '0': 24" - ] - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createOffer", - "description": "Create an offer within your Chargify site by sending a POST request.\n\n## Documentation\n\nOffers allow you to package complicated combinations of products, components and coupons into a convenient package which can then be subscribed to just like products.\n\nOnce an offer is defined it can be used as an alternative to the product when creating subscriptions.\n\nFull documentation on how to use offers in the Chargify UI can be located [here](https://chargify.zendesk.com/hc/en-us/articles/4407753852059).\n\n## Using a Product Price Point\n\nYou can optionally pass in a `product_price_point_id` that corresponds with the `product_id` and the offer will use that price point. If a `product_price_point_id` is not passed in, the product's default price point will be used.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Offer-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "offer": { - "name": "Solo", - "handle": "han_shot_first", - "description": "A Star Wars Story", - "product_id": 31, - "product_price_point_id": 102, - "components": [ - { - "component_id": 24, - "starting_quantity": 1 - } - ], - "coupons": [ - "DEF456" - ] - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Offers", - "tags": [ - "Offers" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Offers-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "offers": [ - { - "id": 239, - "site_id": 48110, - "product_family_id": 1025627, - "product_family_name": "Gold", - "product_id": 110, - "product_name": "Pro", - "product_price_in_cents": 1000, - "product_revisable_number": 0, - "product_price_point_id": 138, - "product_price_point_name": "Default", - "name": "Third Offer", - "handle": "third", - "description": "", - "created_at": "2018-08-03T09:56:11-05:00", - "updated_at": "2018-08-03T09:56:11-05:00", - "archived_at": null, - "offer_items": [ - { - "component_id": 426665, - "component_name": "Database Size (GB)", - "component_unit_price": "1.0", - "price_point_id": 149438, - "price_point_name": "Auto-created", - "starting_quantity": "0.0", - "editable": false, - "currency_prices": [] - } - ], - "offer_discounts": [ - { - "coupon_id": 234, - "coupon_code": "GR8_CUSTOMER", - "coupon_name": "Multi-service Discount" - } - ], - "offer_signup_pages": [ - { - "id": 356482, - "nickname": "ggoods", - "enabled": true, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargifypay.com/subscribe/hjpvhnw63tzy" - } - ] - } - ] - } - } - } - } - } - } - }, - "operationId": "listOffers", - "description": "This endpoint will list offers for a site.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "boolean", - "example": true - }, - "in": "query", - "name": "include_archived", - "description": "Include archived products. Use in query: `include_archived=true`." - } - ] - } - }, - "/offers/{offer_id}.json": { - "parameters": [ - { - "$ref": "../components/parameters/offer-id-path.yaml" - } - ], - "get": { - "summary": "Read Offer", - "tags": [ - "Offers" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Offer-Response.yaml" - }, - "examples": {} - } - } - } - }, - "operationId": "readOffer", - "description": "This method allows you to list a specific offer's attributes. This is different than list all offers for a site, as it requires an `offer_id`." - } - }, - "/offers/{offer_id}/archive.json": { - "parameters": [ - { - "$ref": "../components/parameters/offer-id-path.yaml" - } - ], - "put": { - "summary": "Archive Offer", - "tags": [ - "Offers" - ], - "responses": { - "200": { - "description": "OK" - } - }, - "operationId": "archiveOffer", - "description": "Archive an existing offer. Please provide an `offer_id` in order to archive the correct item." - } - }, - "/offers/{offer_id}/unarchive.json": { - "parameters": [ - { - "$ref": "../components/parameters/offer-id-path.yaml" - } - ], - "put": { - "summary": "Unarchive Offer", - "tags": [ - "Offers" - ], - "responses": { - "200": { - "description": "OK" - } - }, - "operationId": "unarchiveOffer", - "description": "Unarchive a previously archived offer. Please provide an `offer_id` in order to un-archive the correct item." - } - }, - "/sellers/{seller_id}/sales_commission_settings.json": { - "parameters": [ - { - "$ref": "../components/parameters/seller-id-path.yaml" - } - ], - "get": { - "summary": "List Sales Commission Settings", - "tags": [ - "Sales Commissions" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Sale-Rep-Settings.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "customer_name": "Ziomek Ziomeczek", - "subscription_id": 81746, - "site_link": "https://chargify9.staging-chargify.com/dashboard", - "site_name": "Chargify", - "subscription_mrr": "$200.00", - "sales_rep_id": 48, - "sales_rep_name": "John Candy" - }, - { - "customer_name": "Ziom Kom", - "subscription_id": 83758, - "site_link": "https://chargify9.staging-chargify.com/dashboard", - "site_name": "Chargify", - "subscription_mrr": "$200.00", - "sales_rep_id": 49, - "sales_rep_name": "Josh Acme" - }, - { - "customer_name": "George Bush", - "subscription_id": 83790, - "site_link": "https://chargify9.staging-chargify.com/dashboard", - "site_name": "Chargify", - "subscription_mrr": "$200.00", - "sales_rep_id": 48, - "sales_rep_name": "John Candy" - } - ] - } - } - } - } - } - }, - "operationId": "listSalesCommissionSettings", - "description": "Endpoint returns subscriptions with associated sales reps\n\n## Modified Authentication Process\n\nThe Sales Commission API differs from other Chargify API endpoints. This resource is associated with the seller itself. Up to now all available resources were at the level of the site, therefore creating the API Key per site was a sufficient solution. To share resources at the seller level, a new authentication method was introduced, which is user authentication. Creating an API Key for a user is a required step to correctly use the Sales Commission API, more details [here](https://developers.chargify.com/docs/developer-docs/ZG9jOjMyNzk5NTg0-2020-04-20-new-api-authentication).\n\nAccess to the Sales Commission API endpoints is available to users with financial access, where the seller has the Advanced Analytics component enabled. For further information on getting access to Advanced Analytics please contact Chargify support.\n\n> Note: The request is at seller level, it means `<>` variable will be replaced by `app`", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/user-authorization.yaml" - }, - { - "$ref": "../components/parameters/live-mode.yaml" - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page-sales-commission.yaml" - } - ] - } - }, - "/sellers/{seller_id}/sales_reps.json": { - "parameters": [ - { - "$ref": "../components/parameters/seller-id-path.yaml" - } - ], - "get": { - "summary": "List Sales Reps", - "tags": [ - "Sales Commissions" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/List-Sale-Rep-Item.yaml" - } - }, - "examples": { - "Example": { - "value": [ - { - "id": 48, - "full_name": "John Candy", - "subscriptions_count": 2, - "mrr_data": { - "november_2019": { - "mrr": "$0.00", - "usage": "$0.00", - "recurring": "$0.00" - }, - "december_2019": { - "mrr": "$0.00", - "usage": "$0.00", - "recurring": "$0.00" - }, - "january_2020": { - "mrr": "$400.00", - "usage": "$0.00", - "recurring": "$400.00" - }, - "february_2020": { - "mrr": "$400.00", - "usage": "$0.00", - "recurring": "$400.00" - }, - "march_2020": { - "mrr": "$400.00", - "usage": "$0.00", - "recurring": "$400.00" - }, - "april_2020": { - "mrr": "$400.00", - "usage": "$0.00", - "recurring": "$400.00" - } - }, - "test_mode": true - }, - { - "id": 49, - "full_name": "Josh Acme", - "subscriptions_count": 1, - "mrr_data": { - "november_2019": { - "mrr": "$0.00", - "usage": "$0.00", - "recurring": "$0.00" - }, - "december_2019": { - "mrr": "$0.00", - "usage": "$0.00", - "recurring": "$0.00" - }, - "january_2020": { - "mrr": "$200.00", - "usage": "$0.00", - "recurring": "$200.00" - }, - "february_2020": { - "mrr": "$200.00", - "usage": "$0.00", - "recurring": "$200.00" - }, - "march_2020": { - "mrr": "$200.00", - "usage": "$0.00", - "recurring": "$200.00" - }, - "april_2020": { - "mrr": "$200.00", - "usage": "$0.00", - "recurring": "$200.00" - } - }, - "test_mode": true - } - ] - } - } - } - } - } - }, - "operationId": "listSalesReps", - "description": "Endpoint returns sales rep list with details\n\n## Modified Authentication Process\n\nThe Sales Commission API differs from other Chargify API endpoints. This resource is associated with the seller itself. Up to now all available resources were at the level of the site, therefore creating the API Key per site was a sufficient solution. To share resources at the seller level, a new authentication method was introduced, which is user authentication. Creating an API Key for a user is a required step to correctly use the Sales Commission API, more details [here](https://developers.chargify.com/docs/developer-docs/ZG9jOjMyNzk5NTg0-2020-04-20-new-api-authentication).\n\nAccess to the Sales Commission API endpoints is available to users with financial access, where the seller has the Advanced Analytics component enabled. For further information on getting access to Advanced Analytics please contact Chargify support.\n\n> Note: The request is at seller level, it means `<>` variable will be replaced by `app`", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/user-authorization.yaml" - }, - { - "$ref": "../components/parameters/live-mode.yaml" - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page-sales-commission.yaml" - } - ] - } - }, - "/sellers/{seller_id}/sales_reps/{sales_rep_id}.json": { - "parameters": [ - { - "$ref": "../components/parameters/seller-id-path.yaml" - }, - { - "schema": { - "type": "string" - }, - "name": "sales_rep_id", - "in": "path", - "required": true, - "description": "The Chargify id of sales rep." - } - ], - "get": { - "summary": "Read Sales Rep", - "tags": [ - "Sales Commissions" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Sale-Rep.yaml" - }, - "examples": { - "Example": { - "value": { - "id": 48, - "full_name": "John Candy", - "subscriptions_count": 2, - "test_mode": true, - "subscriptions": [ - { - "id": 81746, - "site_name": "Chargify", - "subscription_url": "https://chargify9.staging-chargify.com/subscriptions/81746", - "customer_name": "Ziomek Ziomeczek", - "created_at": "2020-01-03T02:36:27-05:00", - "mrr": "$200.00", - "usage": "$0.00", - "recurring": "$200.00", - "last_payment": "2020-04-03T03:40:27-04:00", - "churn_date": null - }, - { - "id": 83790, - "site_name": "Chargify", - "subscription_url": "https://chargify9.staging-chargify.com/subscriptions/83790", - "customer_name": "George Bush", - "created_at": "2020-01-17T07:34:32-05:00", - "mrr": "$200.00", - "usage": "$0.00", - "recurring": "$200.00", - "last_payment": "2020-04-17T08:41:03-04:00", - "churn_date": null - } - ] - } - } - } - } - } - } - }, - "operationId": "readSalesRep", - "description": "Endpoint returns sales rep and attached subscriptions details.\n\n## Modified Authentication Process\n\nThe Sales Commission API differs from other Chargify API endpoints. This resource is associated with the seller itself. Up to now all available resources were at the level of the site, therefore creating the API Key per site was a sufficient solution. To share resources at the seller level, a new authentication method was introduced, which is user authentication. Creating an API Key for a user is a required step to correctly use the Sales Commission API, more details [here](https://developers.chargify.com/docs/developer-docs/ZG9jOjMyNzk5NTg0-2020-04-20-new-api-authentication).\n\nAccess to the Sales Commission API endpoints is available to users with financial access, where the seller has the Advanced Analytics component enabled. For further information on getting access to Advanced Analytics please contact Chargify support.\n\n> Note: The request is at seller level, it means `<>` variable will be replaced by `app`", - "parameters": [ - { - "$ref": "../components/parameters/user-authorization.yaml" - }, - { - "$ref": "../components/parameters/live-mode.yaml" - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page-sales-commission.yaml" - } - ] - } - }, - "/subscriptions/{subscription_id}/retry.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "put": { - "summary": "Retry Subscription", - "tags": [ - "Subscription Status" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "id": 46330, - "state": "active", - "trial_started_at": null, - "trial_ended_at": null, - "activated_at": "2018-10-22T13:10:46-06:00", - "created_at": "2018-10-22T13:10:46-06:00", - "updated_at": "2021-06-10T09:23:43-06:00", - "expires_at": null, - "balance_in_cents": 18600, - "current_period_ends_at": "2021-06-22T13:10:46-06:00", - "next_assessment_at": "2021-06-22T13:10:46-06:00", - "canceled_at": null, - "cancellation_message": null, - "next_product_id": null, - "cancel_at_end_of_period": null, - "payment_collection_method": "automatic", - "snap_day": null, - "cancellation_method": null, - "product_price_point_id": 3464, - "next_product_price_point_id": null, - "receives_invoice_emails": null, - "net_terms": null, - "locale": null, - "currency": "USD", - "reference": null, - "scheduled_cancellation_at": null, - "current_period_started_at": "2021-05-22T13:10:46-06:00", - "previous_state": "past_due", - "signup_payment_id": 651268, - "signup_revenue": "6.00", - "delayed_cancel_at": null, - "coupon_code": null, - "total_revenue_in_cents": 600, - "product_price_in_cents": 600, - "product_version_number": 501, - "payment_type": null, - "referral_code": "rzqvrx", - "coupon_use_count": null, - "coupon_uses_allowed": null, - "reason_code": null, - "automatically_resume_at": null, - "coupon_codes": [], - "offer_id": null, - "credit_balance_in_cents": 0, - "prepayment_balance_in_cents": 0, - "payer_id": 142365, - "stored_credential_transaction_id": null, - "next_product_handle": null, - "on_hold_at": null, - "prepaid_dunning": false, - "customer": { - "id": 142365, - "first_name": "Lavern", - "last_name": "Fahey", - "organization": null, - "email": "millie2@example.com", - "created_at": "2018-10-22T13:10:46-06:00", - "updated_at": "2018-10-22T13:10:46-06:00", - "reference": null, - "address": null, - "address_2": null, - "city": null, - "state": null, - "zip": null, - "country": null, - "phone": null, - "portal_invite_last_sent_at": null, - "portal_invite_last_accepted_at": null, - "verified": false, - "portal_customer_created_at": "2018-10-22T13:10:46-06:00", - "vat_number": null, - "cc_emails": "john@example.com, sue@example.com", - "tax_exempt": false, - "parent_id": null, - "locale": null - }, - "product": { - "id": 8080, - "name": "Pro Versions", - "handle": null, - "description": "", - "accounting_code": "", - "request_credit_card": true, - "expiration_interval": null, - "expiration_interval_unit": "month", - "created_at": "2019-02-15T10:15:00-07:00", - "updated_at": "2019-02-15T10:30:34-07:00", - "price_in_cents": 600, - "interval": 1, - "interval_unit": "month", - "initial_charge_in_cents": null, - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": true, - "return_params": "", - "require_shipping_address": false, - "request_billing_address": false, - "require_billing_address": false, - "taxable": false, - "update_return_url": "", - "tax_code": "", - "initial_charge_after_trial": false, - "default_product_price_point_id": 3464, - "version_number": 501, - "update_return_params": "", - "product_price_point_id": 3464, - "product_price_point_name": "Default", - "product_price_point_handle": "uuid:5305c3f0-1375-0137-5619-065dfbfdc636", - "product_family": { - "id": 37, - "name": "Acme Projects", - "description": null, - "handle": "acme-projects", - "accounting_code": null, - "created_at": "2013-02-20T15:05:51-07:00", - "updated_at": "2013-02-20T15:05:51-07:00" - }, - "public_signup_pages": [ - { - "id": 1540, - "return_url": null, - "return_params": "", - "url": "https://acme-test.staging-chargifypay.com/subscribe/2f6y53rrqgsf" - } - ] - } - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "base: subscription retry was unsuccessful" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "retrySubscription", - "description": "Chargify offers the ability to retry collecting the balance due on a past due Subscription without waiting for the next scheduled attempt.\n\n## Successful Reactivation\n\nThe response will be `200 OK` with the updated Subscription.\n\n## Failed Reactivation\n\nThe response will be `422 \"Unprocessable Entity`." - } - }, - "/subscriptions/{subscription_id}.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "put": { - "summary": "Update Subscription", - "tags": [ - "Subscriptions" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "id": 18220670, - "state": "active", - "trial_started_at": null, - "trial_ended_at": null, - "activated_at": "2017-06-27T13:45:15-05:00", - "created_at": "2017-06-27T13:45:13-05:00", - "updated_at": "2017-06-30T09:26:50-05:00", - "expires_at": null, - "balance_in_cents": 10000, - "current_period_ends_at": "2017-06-30T12:00:00-05:00", - "next_assessment_at": "2017-06-30T12:00:00-05:00", - "canceled_at": null, - "cancellation_message": null, - "next_product_id": null, - "cancel_at_end_of_period": false, - "payment_collection_method": "automatic", - "snap_day": "end", - "cancellation_method": null, - "current_period_started_at": "2017-06-27T13:45:13-05:00", - "previous_state": "active", - "signup_payment_id": 191819284, - "signup_revenue": "0.00", - "delayed_cancel_at": null, - "coupon_code": null, - "total_revenue_in_cents": 0, - "product_price_in_cents": 0, - "product_version_number": 1, - "payment_type": null, - "referral_code": "d3pw7f", - "coupon_use_count": null, - "coupon_uses_allowed": null, - "reason_code": null, - "automatically_resume_at": null, - "current_billing_amount_in_cents": 10000, - "receives_invoice_emails": false, - "customer": { - "id": 17780587, - "first_name": "Catie", - "last_name": "Test", - "organization": "Acme, Inc.", - "email": "catie@example.com", - "created_at": "2017-06-27T13:01:05-05:00", - "updated_at": "2017-06-30T09:23:10-05:00", - "reference": "123ABC", - "address": "123 Anywhere Street", - "address_2": "Apartment #10", - "city": "Los Angeles", - "state": "CA", - "zip": "90210", - "country": "US", - "phone": "555-555-5555", - "portal_invite_last_sent_at": "2017-06-27T13:45:16-05:00", - "portal_invite_last_accepted_at": null, - "verified": true, - "portal_customer_created_at": "2017-06-27T13:01:08-05:00", - "cc_emails": "support@example.com", - "tax_exempt": true - }, - "product": { - "id": 4470347, - "name": "Zero Dollar Product", - "handle": "zero-dollar-product", - "description": "", - "accounting_code": "", - "request_credit_card": true, - "expiration_interval": null, - "expiration_interval_unit": "never", - "created_at": "2017-03-23T10:54:12-05:00", - "updated_at": "2017-04-20T15:18:46-05:00", - "price_in_cents": 0, - "interval": 1, - "interval_unit": "month", - "initial_charge_in_cents": null, - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": false, - "return_params": "", - "taxable": false, - "update_return_url": "", - "tax_code": "", - "initial_charge_after_trial": false, - "version_number": 1, - "update_return_params": "", - "product_family": { - "id": 997233, - "name": "Acme Products", - "description": "", - "handle": "acme-products", - "accounting_code": null - }, - "public_signup_pages": [ - { - "id": 316810, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/69x825m78v3d/zero-dollar-product" - } - ] - } - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Payment collection method cannot be set to 'invoice' when the subscription is past due", - "'expires_at' cannot be set for subscriptions on calendar billing" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updateSubscription", - "description": "The subscription endpoint allows you to instantly update one or many attributes about a subscription in a single call.\n\n## Update Subscription Payment Method\n\nChange the card that your Subscriber uses for their subscription. You can also use this method to simply change the expiration date of the card **if your gateway allows**.\n\nNote that partial card updates for **Authorize.Net** are not allowed via this endpoint. The existing Payment Profile must be directly updated instead.\n\nYou also use this method to change the subscription to a different product by setting a new value for product_handle. A product change can be done in two different ways, **product change** or **delayed product change**.\n\n## Product Change\n\nThis endpoint may be used to change a subscription's product. The new payment amount is calculated and charged at the normal start of the next period. If you desire complex product changes or prorated upgrades and downgrades instead, please see the documentation on Migrating Subscription Products.\n\nTo perform a product change, simply set either the `product_handle` or `product_id` attribute to that of a different product from the same site as the subscription. You can also change the price point by passing in either `product_price_point_id` or `product_price_point_handle` - otherwise the new product's default price point will be used.\n\n### Delayed Product Change\n\nThis method also changes the product and/or price point, and the new payment amount is calculated and charged at the normal start of the next period.\n\nThis method schedules the product change to happen automatically at the subscription’s next renewal date. To perform a Delayed Product Change, set the `product_handle` attribute as you would in a regular product change, but also set the `product_change_delayed` attribute to `true`. No proration applies in this case.\n\nYou can also perform a delayed change to the price point by passing in either `product_price_point_id` or `product_price_point_handle`\n\n**Note: To cancel a delayed product change, set `next_product_id` to an empty string.**\n\n## Billing Date Changes\n\n### Regular Billing Date Changes\n\nSend the `next_billing_at` to set the next billing date for the subscription. After that date passes and the subscription is processed, the following billing date will be set according to the subscription's product period.\n\nNote that if you pass an invalid date, we will automatically interpret and set the correct date. For example, when February 30 is entered, the next billing will be set to March 2nd in a non-leap year.\n\nThe server response will not return data under the key/value pair of `next_billing`. Please view the key/value pair of `current_period_ends_at` to verify that the `next_billing` date has been changed successfully.\n\n### Snap Day Changes\n\nFor a subscription using Calendar Billing, setting the next billing date is a bit different. Send the `snap_day` attribute to change the calendar billing date for **a subscription using a product eligible for calendar billing**.\n\nNote: If you change the product associated with a subscription that contains a `snap_date` and immediately `READ/GET` the subscription data, it will still contain evidence of the existing `snap_date`. This is due to the fact that a product change is instantanous and only affects the product associated with a subscription. After the `next_billing` date arrives, the `snap_day` associated with the subscription will return to `null.` Another way of looking at this is that you willl have to wait for the next billing cycle to arrive before the `snap_date` will reset to `null`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Subscription-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "credit_card_attributes": { - "full_number": "4111111111111111", - "expiration_month": "10", - "expiration_year": "2030" - }, - "next_billing_at": "2010-08-06T15:34:00Z" - } - } - }, - "With Custom Pricing": { - "value": { - "subscription": { - "product_id": 123, - "custom_price": { - "price_in_cents": 9900, - "interval": 1, - "interval_unit": "month" - }, - "components": [ - { - "component_id": 20, - "custom_price": { - "pricing_scheme": "stairstep", - "prices": [ - { - "unit_price": "5", - "starting_quantity": "1", - "ending_quantity": "15" - }, - { - "unit_price": "2", - "starting_quantity": "16" - } - ] - } - }, - { - "component_id": 10, - "custom_price": { - "prices": [ - { - "unit_price": "1", - "starting_quantity": "1" - } - ] - } - } - ] - } - } - } - } - } - } - } - }, - "delete": { - "summary": "Cancel Subscription", - "tags": [ - "Subscription Status" - ], - "operationId": "cancelSubscription", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "id": 15254809, - "state": "canceled", - "trial_started_at": null, - "trial_ended_at": null, - "activated_at": "2016-11-15T15:33:44-05:00", - "created_at": "2016-11-15T15:33:44-05:00", - "updated_at": "2016-11-15T17:13:06-05:00", - "expires_at": null, - "balance_in_cents": 0, - "current_period_ends_at": "2017-08-29T12:00:00-04:00", - "next_assessment_at": "2017-08-29T12:00:00-04:00", - "canceled_at": "2016-11-15T17:13:06-05:00", - "cancellation_message": "Canceling the subscription via the API", - "next_product_id": null, - "cancel_at_end_of_period": false, - "payment_collection_method": "automatic", - "snap_day": null, - "cancellation_method": "merchant_api", - "current_period_started_at": "2016-11-15T15:33:44-05:00", - "previous_state": "active", - "signup_payment_id": 0, - "signup_revenue": "0.00", - "delayed_cancel_at": null, - "coupon_code": null, - "total_revenue_in_cents": 0, - "product_price_in_cents": 1000, - "product_version_number": 7, - "payment_type": "credit_card", - "referral_code": "tg8qbq", - "coupon_use_count": null, - "coupon_uses_allowed": null, - "customer": { - "id": 14731081, - "first_name": "John", - "last_name": "Doe", - "organization": "Acme Widgets", - "email": "john.doe@example.com", - "created_at": "2016-11-15T15:33:44-05:00", - "updated_at": "2016-11-15T15:33:45-05:00", - "reference": "123", - "address": null, - "address_2": null, - "city": null, - "state": null, - "zip": null, - "country": null, - "phone": null, - "portal_invite_last_sent_at": "2016-11-15T15:33:45-05:00", - "portal_invite_last_accepted_at": null, - "verified": false, - "portal_customer_created_at": "2016-11-15T15:33:45-05:00", - "cc_emails": null - }, - "product": { - "id": 3792003, - "name": "$10 Basic Plan", - "handle": "basic", - "description": "lorem ipsum", - "accounting_code": "basic", - "request_credit_card": false, - "expiration_interval": null, - "expiration_interval_unit": "never", - "created_at": "2016-03-24T13:38:39-04:00", - "updated_at": "2016-11-03T13:03:05-04:00", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "day", - "initial_charge_in_cents": null, - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": false, - "return_params": "", - "taxable": false, - "update_return_url": "", - "initial_charge_after_trial": false, - "version_number": 7, - "update_return_params": "", - "product_family": { - "id": 527890, - "name": "Acme Projects", - "description": "", - "handle": "billing-plans", - "accounting_code": null - }, - "public_signup_pages": [ - { - "id": 281054, - "return_url": "http://www.example.com?successfulsignup", - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/kqvmfrbgd89q/basic" - }, - { - "id": 281240, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/dkffht5dxfd8/basic" - }, - { - "id": 282694, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/jwffwgdd95s8/basic" - } - ] - }, - "credit_card": { - "id": 10202898, - "first_name": "John", - "last_name": "Doe", - "masked_card_number": "XXXX-XXXX-XXXX-1111", - "card_type": "visa", - "expiration_month": 12, - "expiration_year": 2020, - "customer_id": 14731081, - "current_vault": "authorizenet", - "vault_token": "12345", - "billing_address": null, - "billing_city": null, - "billing_state": null, - "billing_zip": null, - "billing_country": null, - "customer_vault_token": "67890", - "billing_address_2": null, - "payment_type": "credit_card" - } - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Cancel-Subscription-Error-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "error": "The subscription is already canceled" - } - }, - "Example-2": { - "value": { - "errors": [ - "reason_code size cannot be greater than 255", - "cancellation_message size cannot be greater than 65535" - ] - } - }, - "Example-3": { - "value": { - "errors": [ - "subscription must be an Object" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "description": "The DELETE action causes the cancellation of the Subscription. This means, the method sets the Subscription state to \"canceled\".", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Cancellation-Request.yaml" - } - } - } - } - }, - "get": { - "summary": "Read Subscription", - "tags": [ - "Subscriptions" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "id": 15236915, - "state": "active", - "balance_in_cents": 0, - "total_revenue_in_cents": 14000, - "product_price_in_cents": 1000, - "product_version_number": 7, - "current_period_ends_at": "2016-11-15T14:48:10-05:00", - "next_assessment_at": "2016-11-15T14:48:10-05:00", - "trial_started_at": null, - "trial_ended_at": null, - "activated_at": "2016-11-14T14:48:12-05:00", - "expires_at": null, - "created_at": "2016-11-14T14:48:10-05:00", - "updated_at": "2016-11-14T15:24:41-05:00", - "cancellation_message": null, - "cancellation_method": null, - "cancel_at_end_of_period": null, - "canceled_at": null, - "current_period_started_at": "2016-11-14T14:48:10-05:00", - "previous_state": "active", - "signup_payment_id": 162269766, - "signup_revenue": "260.00", - "delayed_cancel_at": null, - "coupon_code": "5SNN6HFK3GBH", - "payment_collection_method": "automatic", - "snap_day": null, - "reason_code": null, - "receives_invoice_emails": false, - "net_terms": 0, - "customer": { - "first_name": "Curtis", - "last_name": "Test", - "email": "curtis@example.com", - "cc_emails": "jeff@example.com", - "organization": "", - "reference": null, - "id": 14714298, - "created_at": "2016-11-14T14:48:10-05:00", - "updated_at": "2016-11-14T14:48:13-05:00", - "address": "123 Anywhere Street", - "address_2": "", - "city": "Boulder", - "state": "CO", - "zip": "80302", - "country": "US", - "phone": "", - "verified": false, - "portal_customer_created_at": "2016-11-14T14:48:13-05:00", - "portal_invite_last_sent_at": "2016-11-14T14:48:13-05:00", - "portal_invite_last_accepted_at": null, - "tax_exempt": false, - "vat_number": "012345678" - }, - "product": { - "id": 3792003, - "name": "$10 Basic Plan", - "handle": "basic", - "description": "lorem ipsum", - "accounting_code": "basic", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "day", - "initial_charge_in_cents": null, - "expiration_interval": null, - "expiration_interval_unit": "never", - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": "month", - "initial_charge_after_trial": false, - "return_params": "", - "request_credit_card": false, - "require_credit_card": false, - "created_at": "2016-03-24T13:38:39-04:00", - "updated_at": "2016-11-03T13:03:05-04:00", - "archived_at": null, - "update_return_url": "", - "update_return_params": "", - "product_family": { - "id": 527890, - "name": "Acme Projects", - "handle": "billing-plans", - "accounting_code": null, - "description": "" - }, - "public_signup_pages": [ - { - "id": 281054, - "url": "https://general-goods.chargify.com/subscribe/kqvmfrbgd89q/basic" - }, - { - "id": 281240, - "url": "https://general-goods.chargify.com/subscribe/dkffht5dxfd8/basic" - }, - { - "id": 282694, - "url": "https://general-goods.chargify.com/subscribe/jwffwgdd95s8/basic" - } - ], - "taxable": false, - "version_number": 7, - "product_price_point_name": "Default" - }, - "credit_card": { - "id": 10191713, - "payment_type": "credit_card", - "first_name": "Curtis", - "last_name": "Test", - "masked_card_number": "XXXX-XXXX-XXXX-1", - "card_type": "bogus", - "expiration_month": 1, - "expiration_year": 2026, - "billing_address": "123 Anywhere Street", - "billing_address_2": "", - "billing_city": "Boulder", - "billing_state": null, - "billing_country": "", - "billing_zip": "80302", - "current_vault": "bogus", - "vault_token": "1", - "customer_vault_token": null, - "customer_id": 14714298 - }, - "payment_type": "credit_card", - "referral_code": "w7kjc9", - "next_product_id": null, - "coupon_use_count": 1, - "coupon_uses_allowed": 1, - "stored_credential_transaction_id": 166411599220288, - "on_hold_at": null, - "scheduled_cancellation_at": "2016-11-14T14:48:13-05:00" - } - } - } - } - } - } - } - }, - "operationId": "readSubscription", - "description": "Use this endpoint to find subscription details.\n\n## Self-Service Page token\n\nSelf-Service Page token for the subscription is not returned by default. If this information is desired, the include[]=self_service_page_token parameter must be provided with the request.", - "parameters": [ - { - "name": "include[]", - "in": "query", - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Subscription-Include.yaml" - }, - "example": [ - "coupons", - "self_service_page_token" - ] - }, - "style": "form", - "explode": true, - "description": "Allows including additional data in the response. Use in query: `include[]=coupons&include[]=self_service_page_token`." - } - ] - } - }, - "/subscriptions/{subscription_id}/resume.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Resume Subscription", - "tags": [ - "Subscription Status" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "id": 18220670, - "state": "active", - "trial_started_at": null, - "trial_ended_at": null, - "activated_at": "2017-06-27T13:45:15-05:00", - "created_at": "2017-06-27T13:45:13-05:00", - "updated_at": "2017-06-30T09:26:50-05:00", - "expires_at": null, - "balance_in_cents": 10000, - "current_period_ends_at": "2017-06-30T12:00:00-05:00", - "next_assessment_at": "2017-06-30T12:00:00-05:00", - "canceled_at": null, - "cancellation_message": null, - "next_product_id": null, - "cancel_at_end_of_period": false, - "payment_collection_method": "automatic", - "snap_day": "end", - "cancellation_method": null, - "current_period_started_at": "2017-06-27T13:45:13-05:00", - "previous_state": "active", - "signup_payment_id": 191819284, - "signup_revenue": "0.00", - "delayed_cancel_at": null, - "coupon_code": null, - "total_revenue_in_cents": 0, - "product_price_in_cents": 0, - "product_version_number": 1, - "payment_type": null, - "referral_code": "d3pw7f", - "coupon_use_count": null, - "coupon_uses_allowed": null, - "reason_code": null, - "automatically_resume_at": null, - "current_billing_amount_in_cents": 10000, - "customer": { - "id": 17780587, - "first_name": "Catie", - "last_name": "Test", - "organization": "Acme, Inc.", - "email": "catie@example.com", - "created_at": "2017-06-27T13:01:05-05:00", - "updated_at": "2017-06-30T09:23:10-05:00", - "reference": "123ABC", - "address": "123 Anywhere Street", - "address_2": "Apartment #10", - "city": "Los Angeles", - "state": "CA", - "zip": "90210", - "country": "US", - "phone": "555-555-5555", - "portal_invite_last_sent_at": "2017-06-27T13:45:16-05:00", - "portal_invite_last_accepted_at": null, - "verified": true, - "portal_customer_created_at": "2017-06-27T13:01:08-05:00", - "cc_emails": "support@example.com", - "tax_exempt": true - }, - "product": { - "id": 4470347, - "name": "Zero Dollar Product", - "handle": "zero-dollar-product", - "description": "", - "accounting_code": "", - "request_credit_card": true, - "expiration_interval": null, - "expiration_interval_unit": "never", - "created_at": "2017-03-23T10:54:12-05:00", - "updated_at": "2017-04-20T15:18:46-05:00", - "price_in_cents": 0, - "interval": 1, - "interval_unit": "month", - "initial_charge_in_cents": null, - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": false, - "return_params": "", - "taxable": false, - "update_return_url": "", - "tax_code": "", - "initial_charge_after_trial": false, - "version_number": 1, - "update_return_params": "", - "product_family": { - "id": 997233, - "name": "Acme Products", - "description": "", - "handle": "acme-products", - "accounting_code": null - }, - "public_signup_pages": [ - { - "id": 316810, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/69x825m78v3d/zero-dollar-product" - } - ] - } - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Only subscriptions that are on hold can be resumed." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "resumeSubscription", - "description": "Resume a paused (on-hold) subscription. If the normal next renewal date has not passed, the subscription will return to active and will renew on that date. Otherwise, it will behave like a reactivation, setting the billing date to 'now' and charging the subscriber.", - "parameters": [ - { - "schema": { - "$ref": "../components/schemas/Resumption-Charge.yaml" - }, - "in": "query", - "name": "calendar_billing['resumption_charge']", - "description": "(For calendar billing subscriptions only) The way that the resumed subscription's charge should be handled" - } - ] - } - }, - "/subscriptions/{subscription_id}/hold.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Hold / Pause Subscription", - "tags": [ - "Subscription Status" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "id": 18220670, - "state": "on_hold", - "trial_started_at": null, - "trial_ended_at": null, - "activated_at": "2017-06-27T13:45:15-05:00", - "created_at": "2017-06-27T13:45:13-05:00", - "updated_at": "2017-06-30T09:26:50-05:00", - "expires_at": null, - "balance_in_cents": 10000, - "current_period_ends_at": "2017-06-30T12:00:00-05:00", - "next_assessment_at": "2017-06-30T12:00:00-05:00", - "canceled_at": null, - "cancellation_message": null, - "next_product_id": null, - "cancel_at_end_of_period": false, - "payment_collection_method": "automatic", - "snap_day": "end", - "cancellation_method": null, - "current_period_started_at": "2017-06-27T13:45:13-05:00", - "previous_state": "active", - "signup_payment_id": 191819284, - "signup_revenue": "0.00", - "delayed_cancel_at": null, - "coupon_code": null, - "total_revenue_in_cents": 0, - "product_price_in_cents": 0, - "product_version_number": 1, - "payment_type": null, - "referral_code": "d3pw7f", - "coupon_use_count": null, - "coupon_uses_allowed": null, - "reason_code": null, - "automatically_resume_at": null, - "current_billing_amount_in_cents": 10000, - "customer": { - "id": 17780587, - "first_name": "Catie", - "last_name": "Test", - "organization": "Acme, Inc.", - "email": "catie@example.com", - "created_at": "2017-06-27T13:01:05-05:00", - "updated_at": "2017-06-30T09:23:10-05:00", - "reference": "123ABC", - "address": "123 Anywhere Street", - "address_2": "Apartment #10", - "city": "Los Angeles", - "state": "CA", - "zip": "90210", - "country": "US", - "phone": "555-555-5555", - "portal_invite_last_sent_at": "2017-06-27T13:45:16-05:00", - "portal_invite_last_accepted_at": null, - "verified": true, - "portal_customer_created_at": "2017-06-27T13:01:08-05:00", - "cc_emails": "support@example.com", - "tax_exempt": true - }, - "product": { - "id": 4470347, - "name": "Zero Dollar Product", - "handle": "zero-dollar-product", - "description": "", - "accounting_code": "", - "request_credit_card": true, - "expiration_interval": null, - "expiration_interval_unit": "never", - "created_at": "2017-03-23T10:54:12-05:00", - "updated_at": "2017-04-20T15:18:46-05:00", - "price_in_cents": 0, - "interval": 1, - "interval_unit": "month", - "initial_charge_in_cents": null, - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": false, - "return_params": "", - "taxable": false, - "update_return_url": "", - "tax_code": "", - "initial_charge_after_trial": false, - "version_number": 1, - "update_return_params": "", - "product_family": { - "id": 997233, - "name": "Acme Products", - "description": "", - "handle": "acme-products", - "accounting_code": null - }, - "public_signup_pages": [ - { - "id": 316810, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/69x825m78v3d/zero-dollar-product" - } - ] - } - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "This subscription is not eligible to be put on hold." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "pauseSubscription", - "description": "This will place the subscription in the on_hold state and it will not renew.\n\n## Limitations\n\nYou may not place a subscription on hold if the `next_billing` date is within 24 hours.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Pause-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "hold": { - "automatically_resume_at": "2017-05-25T11:25:00Z" - } - } - } - } - } - } - } - }, - "put": { - "summary": "Update Automatic Subscription Resumption", - "tags": [ - "Subscription Status" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "id": 20359140, - "state": "on_hold", - "trial_started_at": null, - "trial_ended_at": null, - "activated_at": "2018-01-05T17:15:50-06:00", - "created_at": "2018-01-05T17:15:49-06:00", - "updated_at": "2018-01-09T10:26:14-06:00", - "expires_at": null, - "balance_in_cents": 0, - "current_period_ends_at": "2023-01-05T17:15:00-06:00", - "next_assessment_at": "2023-01-05T17:15:00-06:00", - "canceled_at": null, - "cancellation_message": null, - "next_product_id": null, - "cancel_at_end_of_period": false, - "payment_collection_method": "automatic", - "snap_day": null, - "cancellation_method": null, - "current_period_started_at": "2018-01-05T17:15:49-06:00", - "previous_state": "active", - "signup_payment_id": 219829722, - "signup_revenue": "100.00", - "delayed_cancel_at": null, - "coupon_code": null, - "total_revenue_in_cents": 10009991, - "product_price_in_cents": 10000, - "product_version_number": 1, - "payment_type": "credit_card", - "referral_code": "8y7jqr", - "coupon_use_count": null, - "coupon_uses_allowed": null, - "reason_code": null, - "automatically_resume_at": "2019-01-20T00:00:00-06:00", - "coupon_codes": [], - "customer": { - "id": 19948683, - "first_name": "Vanessa", - "last_name": "Test", - "organization": "", - "email": "vanessa@example.com", - "created_at": "2018-01-05T17:15:49-06:00", - "updated_at": "2018-01-05T17:15:51-06:00", - "reference": null, - "address": "123 Anywhere Ln", - "address_2": "", - "city": "Boston", - "state": "MA", - "zip": "02120", - "country": "US", - "phone": "555-555-1212", - "portal_invite_last_sent_at": "2018-01-05T17:15:51-06:00", - "portal_invite_last_accepted_at": null, - "verified": null, - "portal_customer_created_at": "2018-01-05T17:15:51-06:00", - "cc_emails": null, - "tax_exempt": false - }, - "product": { - "id": 4535643, - "name": "Annual Product", - "handle": "annual-product", - "description": "", - "accounting_code": "", - "request_credit_card": true, - "expiration_interval": null, - "expiration_interval_unit": "never", - "created_at": "2017-08-25T10:25:31-05:00", - "updated_at": "2017-08-25T10:25:31-05:00", - "price_in_cents": 10000, - "interval": 12, - "interval_unit": "month", - "initial_charge_in_cents": null, - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": true, - "return_params": "", - "taxable": false, - "update_return_url": "", - "tax_code": "", - "initial_charge_after_trial": false, - "version_number": 1, - "update_return_params": "", - "product_family": { - "id": 1025627, - "name": "Acme Products", - "description": "", - "handle": "acme-products", - "accounting_code": null - }, - "public_signup_pages": [] - }, - "credit_card": { - "id": 13826563, - "first_name": "Bomb 3", - "last_name": "Test", - "masked_card_number": "XXXX-XXXX-XXXX-1", - "card_type": "bogus", - "expiration_month": 1, - "expiration_year": 2028, - "customer_id": 19948683, - "current_vault": "bogus", - "vault_token": "1", - "billing_address": "123 Anywhere Lane", - "billing_city": "Boston", - "billing_state": "Ma", - "billing_zip": "02120", - "billing_country": "US", - "customer_vault_token": null, - "billing_address_2": "", - "payment_type": "credit_card" - } - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "errors": [ - "Subscription is not currently on hold." - ] - } - }, - "Example-2": { - "value": { - "errors": [ - "Automatic resume date: must be at least 24 hours in the future." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updateAutomaticSubscriptionResumption", - "description": "Once a subscription has been paused / put on hold, you can update the date which was specified to automatically resume the subscription.\n\nTo update a subscription's resume date, use this method to change or update the `automatically_resume_at` date.\n\n### Remove the resume date\n\nAlternately, you can change the `automatically_resume_at` to `null` if you would like the subscription to not have a resume date.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Pause-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "hold": { - "automatically_resume_at": "2019-01-20T00:00:00" - } - } - } - } - } - } - } - } - }, - "/subscriptions/{subscription_id}/reactivate.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "put": { - "summary": "Reactivate Subscription", - "tags": [ - "Subscription Status" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "id": 18220670, - "state": "active", - "trial_started_at": null, - "trial_ended_at": null, - "activated_at": "2017-06-27T13:45:15-05:00", - "created_at": "2017-06-27T13:45:13-05:00", - "updated_at": "2017-06-30T09:26:50-05:00", - "expires_at": null, - "balance_in_cents": 10000, - "current_period_ends_at": "2017-06-30T12:00:00-05:00", - "next_assessment_at": "2017-06-30T12:00:00-05:00", - "canceled_at": null, - "cancellation_message": null, - "next_product_id": null, - "cancel_at_end_of_period": false, - "payment_collection_method": "automatic", - "snap_day": "end", - "cancellation_method": null, - "current_period_started_at": "2017-06-27T13:45:13-05:00", - "previous_state": "active", - "signup_payment_id": 191819284, - "signup_revenue": "0.00", - "delayed_cancel_at": null, - "coupon_code": null, - "total_revenue_in_cents": 0, - "product_price_in_cents": 0, - "product_version_number": 1, - "payment_type": null, - "referral_code": "d3pw7f", - "coupon_use_count": null, - "coupon_uses_allowed": null, - "reason_code": null, - "automatically_resume_at": null, - "current_billing_amount_in_cents": 10000, - "customer": { - "id": 17780587, - "first_name": "Catie", - "last_name": "Test", - "organization": "Acme, Inc.", - "email": "catie@example.com", - "created_at": "2017-06-27T13:01:05-05:00", - "updated_at": "2017-06-30T09:23:10-05:00", - "reference": "123ABC", - "address": "123 Anywhere Street", - "address_2": "Apartment #10", - "city": "Los Angeles", - "state": "CA", - "zip": "90210", - "country": "US", - "phone": "555-555-5555", - "portal_invite_last_sent_at": "2017-06-27T13:45:16-05:00", - "portal_invite_last_accepted_at": null, - "verified": true, - "portal_customer_created_at": "2017-06-27T13:01:08-05:00", - "cc_emails": "support@example.com", - "tax_exempt": true, - "vat_number": "012345678" - }, - "product": { - "id": 4470347, - "name": "Zero Dollar Product", - "handle": "zero-dollar-product", - "description": "", - "accounting_code": "", - "request_credit_card": true, - "expiration_interval": null, - "expiration_interval_unit": "never", - "created_at": "2017-03-23T10:54:12-05:00", - "updated_at": "2017-04-20T15:18:46-05:00", - "price_in_cents": 0, - "interval": 1, - "interval_unit": "month", - "initial_charge_in_cents": null, - "trial_price_in_cents": null, - "trial_interval": null, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": false, - "return_params": "", - "taxable": false, - "update_return_url": "", - "tax_code": "", - "initial_charge_after_trial": false, - "version_number": 1, - "update_return_params": "", - "product_family": { - "id": 997233, - "name": "Acme Products", - "description": "", - "handle": "acme-products", - "accounting_code": null - }, - "public_signup_pages": [ - { - "id": 316810, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/69x825m78v3d/zero-dollar-product" - } - ] - } - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Cannot reactivate a subscription that is not marked \"Canceled\", \"Unpaid\", or \"Trial Ended\".", - "Request was 'resume only', but this subscription cannot be resumed.", - "The credit card on file could not be charged." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "reactivateSubscription", - "description": "Chargify offers the ability to reactivate a previously canceled subscription. For details on how the reactivation works, and how to reactivate subscriptions through the application, see [reactivation](https://chargify.zendesk.com/hc/en-us/articles/4407898737691).\n\n**Please note: The term\n\"resume\" is used also during another process in Chargify. This occurs when an on-hold subscription is \"resumed\". This returns the subscription to an active state.**\n\n+ The response returns the subscription object in the `active` or `trialing` state.\n+ The `canceled_at` and `cancellation_message` fields do not have values.\n+ The method works for \"Canceled\" or \"Trial Ended\" subscriptions.\n+ It will not work for items not marked as \"Canceled\", \"Unpaid\", or \"Trial Ended\".\n\n## Resume the current billing period for a subscription\n\nA subscription is considered \"resumable\" if you are attempting to reactivate within the billing period the subscription was canceled in.\n\nA resumed subscription's billing date remains the same as before it was canceled. In other words, it does not start a new billing period. Payment may or may not be collected for a resumed subscription, depending on whether or not the subscription had a balance when it was canceled (for example, if it was canceled because of dunning).\n\nConsider a subscription which was created on June 1st, and would renew on July 1st. The subscription is then canceled on June 15.\n\nIf a reactivation with `resume: true` were attempted _before_ what would have been the next billing date of July 1st, then Chargify would resume the subscription.\n\nIf a reactivation with `resume: true` were attempted _after_ what would have been the next billing date of July 1st, then Chargify would not resume the subscription, and instead it would be reactivated with a new billing period.\n\n| Canceled | Reactivation | Resumable? |\n|---|---|---|\n| Jun 15 | June 28 | Yes |\n| Jun 15 | July 2 | No |\n\n## Reactivation Scenarios\n\n### Reactivating Canceled Subscription While Preserving Balance\n\n+ Given you have a product that costs $20\n+ Given you have a canceled subscription to the $20 product\n + 1 charge should exist for $20\n + 1 payment should exist for $20\n+ When the subscription has canceled due to dunning, it retained a negative balance of $20\n\n#### Results\n\nThe resulting charges upon reactivation will be:\n+ 1 charge for $20 for the new product\n+ 1 charge for $20 for the balance due\n+ Total charges = $40\n\n+ The subscription will transition to active\n+ The subscription balance will be zero\n\n### Reactivating a Canceled Subscription With Coupon\n\n+ Given you have a canceled subscription\n+ It has no current period defined\n+ You have a coupon code \"EARLYBIRD\"\n+ The coupon is set to recur for 6 periods\n\nPUT request sent to:\n`https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?coupon_code=EARLYBIRD`\n\n#### Results\n\n+ The subscription will transition to active\n+ The subscription should have applied a coupon with code \"EARLYBIRD\"\n\n### Reactivating Canceled Subscription With a Trial, Without the include_trial Flag\n\n+ Given you have a canceled subscription\n+ The product associated with the subscription has a trial\n\n+ PUT request to\n`https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json`\n\n\n#### Results\n+ The subscription will transition to active\n\n### Reactivating Canceled Subscription With Trial, With the include_trial Flag\n\n+ Given you have a canceled subscription\n+ The product associated with the subscription has a trial\n\n+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?include_trial=1`\n\n\n#### Results\n\n+ The subscription will transition to trialing\n\n### Reactivating Trial Ended Subscription\n\n+ Given you have a trial_ended subscription\n+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json`\n\n#### Results\n\n+ The subscription will transition to active\n\n### Resuming a Canceled Subscription\n\n+ Given you have a `canceled` subscription and it is resumable\n+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?resume=true`\n\n#### Results\n\n+ The subscription will transition to active\n+ The next billing date should not have changed\n\n### Attempting to resume a subscription which is not resumable\n\n+ Given you have a `canceled` subscription, and it is not resumable\n+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?resume=true`\n\n#### Results\n\n+ The subscription will transition to active, with a new billing period.\n\n### Attempting to resume but not reactivate a subscription which is not resumable\n\n+ Given you have a `canceled` subscription, and it is not resumable\n+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?resume[require_resume]=true`\n+ The response status should be \"422 UNPROCESSABLE ENTITY\"\n+ The subscription should be canceled with the following response\n```\n {\n \"errors\": [\"Request was 'resume only', but this subscription cannot be resumed.\"]\n }\n```\n\n#### Results\n\n+ The subscription should remain `canceled`\n+ The next billing date should not have changed\n\n### Resuming Subscription Which Was Trialing\n\n+ Given you have a `trial_ended` subscription, and it is resumable\n+ And the subscription was canceled in the middle of a trial\n+ And there is still time left on the trial\n+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?resume=true`\n\n#### Results\n\n+ The subscription will transition to trialing\n+ The next billing date should not have changed\n\n### Resuming Subscription Which Was trial_ended\n\n+ Given you have a `trial_ended` subscription, and it is resumable\n+ Send a PUT request to `https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json?resume=true`\n\n#### Results\n\n+ The subscription will transition to active\n+ The next billing date should not have changed\n+ Any product-related charges should have been collected", - "parameters": [], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Reactivate-Subscription-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "calendar_billing": { - "reactivation_charge": "prorated" - }, - "include_trial": true, - "preserve_balance": true, - "coupon_code": "10OFF", - "use_credits_and_prepayments": true, - "resume": true - } - } - } - } - } - } - } - }, - "/subscriptions/{subscription_id}/migrations.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Migrate Subscription Product", - "tags": [ - "Subscription Products" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "id": 15054201, - "state": "trialing", - "trial_started_at": "2016-11-03T13:43:36-04:00", - "trial_ended_at": "2016-11-10T12:43:36-05:00", - "activated_at": "2016-11-02T10:20:57-04:00", - "created_at": "2016-11-02T10:20:55-04:00", - "updated_at": "2016-11-03T13:43:36-04:00", - "expires_at": null, - "balance_in_cents": -13989, - "current_period_ends_at": "2016-11-10T12:43:36-05:00", - "next_assessment_at": "2016-11-10T12:43:36-05:00", - "canceled_at": null, - "cancellation_message": null, - "next_product_id": null, - "cancel_at_end_of_period": false, - "payment_collection_method": "automatic", - "snap_day": null, - "cancellation_method": null, - "current_period_started_at": "2016-11-03T13:43:35-04:00", - "previous_state": "active", - "signup_payment_id": 160680121, - "signup_revenue": "0.00", - "delayed_cancel_at": null, - "coupon_code": null, - "total_revenue_in_cents": 14000, - "product_price_in_cents": 1000, - "product_version_number": 6, - "payment_type": "credit_card", - "referral_code": "ghnhvy", - "coupon_use_count": null, - "coupon_uses_allowed": null, - "customer": { - "id": 14543792, - "first_name": "Frankie", - "last_name": "Test", - "organization": null, - "email": "testfrankie111@test.com", - "created_at": "2016-11-02T10:20:55-04:00", - "updated_at": "2016-11-02T10:20:58-04:00", - "reference": null, - "address": null, - "address_2": null, - "city": null, - "state": null, - "zip": null, - "country": null, - "phone": "5555551212", - "portal_invite_last_sent_at": "2016-11-02T10:20:58-04:00", - "portal_invite_last_accepted_at": null, - "verified": false, - "portal_customer_created_at": "2016-11-02T10:20:58-04:00", - "cc_emails": null - }, - "product": { - "id": 3861800, - "name": "Trial Product", - "handle": "trial-product", - "description": "Trial period with payment expected at end of trial.", - "accounting_code": "", - "request_credit_card": true, - "expiration_interval": null, - "expiration_interval_unit": "never", - "created_at": "2016-07-08T09:53:55-04:00", - "updated_at": "2016-09-05T13:00:36-04:00", - "price_in_cents": 1000, - "interval": 1, - "interval_unit": "month", - "initial_charge_in_cents": null, - "trial_price_in_cents": 0, - "trial_interval": 7, - "trial_interval_unit": "day", - "archived_at": null, - "require_credit_card": true, - "return_params": "", - "taxable": false, - "update_return_url": "", - "initial_charge_after_trial": false, - "version_number": 6, - "update_return_params": "", - "product_family": { - "id": 527890, - "name": "Acme Projects", - "description": "", - "handle": "billing-plans", - "accounting_code": null - }, - "public_signup_pages": [ - { - "id": 294791, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargify.com/subscribe/xv52yrcc3byx/trial-product" - } - ] - }, - "credit_card": { - "id": 10088716, - "first_name": "F", - "last_name": "NB", - "masked_card_number": "XXXX-XXXX-XXXX-1", - "card_type": "bogus", - "expiration_month": 1, - "expiration_year": 2017, - "customer_id": 14543792, - "current_vault": "bogus", - "vault_token": "1", - "billing_address": "123 Montana Way", - "billing_city": "Billings", - "billing_state": "MT", - "billing_zip": "59101", - "billing_country": "US", - "customer_vault_token": null, - "billing_address_2": "Apt. 10", - "payment_type": "credit_card" - } - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "No credit card was on file for the $200.00 balance", - "This subscription is not eligible for a prorated migration", - "Invalid Product" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "migrateSubscriptionProduct", - "description": "In order to create a migration, you must pass the `product_id` or `product_handle` in the object when you send a POST request. You may also pass either a `product_price_point_id` or `product_price_point_handle` to choose which price point the subscription is moved to. If no price point identifier is passed the subscription will be moved to the products default price point. The response will be the updated subscription.\n\n## Valid Subscriptions\n\nSubscriptions should be in the `active` or `trialing` state in order to be migrated.\n\n(For backwards compatibility reasons, it is possible to migrate a subscription that is in the `trial_ended` state via the API, however this is not recommended. Since `trial_ended` is an end-of-life state, the subscription should be canceled, the product changed, and then the subscription can be reactivated.)\n\n## Migrations Documentation\n\nFull documentation on how to record Migrations in the Chargify UI can be located [here](https://chargify.zendesk.com/hc/en-us/articles/4407898373531).\n\n## Failed Migrations\n\nOne of the most common ways that a migration can fail is when the attempt is made to migrate a subscription to it's current product. Please be aware of this issue!\n\n## Migration 3D Secure - Stripe\n\nIt may happen that a payment needs 3D Secure Authentication when the subscription is migrated to a new product; this is referred to in our help docs as a [post-authentication flow](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405177432077#psd2-flows-pre-authentication-and-post-authentication). The server returns `422 Unprocessable Entity` in this case with the following response:\n\n```json\n{\n \"errors\": [\n \"Your card was declined. This transaction requires 3D secure authentication.\"\n ],\n \"gateway_payment_id\": \"pi_1F0aGoJ2UDb3Q4av7zU3sHPh\",\n \"description\": \"This card requires 3D secure authentication. Redirect the customer to the URL from the action_link attribute to authenticate. Attach callback_url param to this URL if you want to be notified about the result of 3D Secure authentication. Attach redirect_url param to this URL if you want to redirect a customer back to your page after 3D Secure authentication. Example: https://mysite.chargify.com/3d-secure/pi_1FCm4RKDeye4C0XfbqquXRYm?one_time_token_id=128&callback_url=https://localhost:4000&redirect_url=https://yourpage.com will do a POST request to https://localhost:4000 after payment is authenticated and will redirect a customer to https://yourpage.com after 3DS authentication.\",\n \"action_link\": \"http://acme.chargify.com/3d-secure/pi_1F0aGoJ2UDb3Q4av7zU3sHPh?one_time_token_id=242\"\n}\n```\n\nTo let the customer go through 3D Secure Authentication, they need to be redirected to the URL specified in `action_link`.\nOptionally, you can specify `callback_url` parameter in the `action_link` URL if you’d like to be notified about the result of 3D Secure Authentication. The `callback_url` will return the following information:\n\n- whether the authentication was successful (`success`)\n- the gateway ID for the payment (`gateway_payment_id`)\n- the subscription ID (`subscription_id`)\n\nLastly, you can also specify a `redirect_url` within the `action_link` URL if you’d like to redirect a customer back to your site.\n\nIt is not possible to use `action_link` in an iframe inside a custom application. You have to redirect the customer directly to the `action_link`, then, to be notified about the result, use `redirect_url` or `callback_url`.\n\nThe final URL that you send a customer to to complete 3D Secure may resemble the following, where the first half is the `action_link` and the second half contains a `redirect_url` and `callback_url`: `https://mysite.chargify.com/3d-secure/pi_1FCm4RKDeye4C0XfbqquXRYm?one_time_token_id=128&callback_url=https://localhost:4000&redirect_url=https://yourpage.com`\n\n### Example Redirect Flow\n\nYou may wish to redirect customers to different pages depending on whether their SCA was performed successfully. Here's an example flow to use as a reference:\n\n1. Create a migration via API; it requires 3DS\n2. You receive a `gateway_payment_id` in the `action_link` along other params in the response.\n3. Use this `gateway_payment_id` to, for example, connect with your internal resources or generate a session_id\n4. Include 1 of those attributes inside the `callback_url` and `redirect_url` to be aware which “session” this applies to\n5. Redirect the customer to the `action_link` with `callback_url` and `redirect_url` applied\n6. After the customer finishes 3DS authentication, we let you know the result by making a request to applied `callback_url`.\n7. After that, we redirect the customer to the `redirect_url`; at this point the result of authentication is known\n8. Optionally, you can use the applied \"msg\" param in the `redirect_url` to determine whether it was successful or not.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Product-Migration-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "migration": { - "product_id": 3801242, - "include_trial": false, - "include_initial_charge": false, - "include_coupons": true, - "preserve_period": true - } - } - } - } - } - } - } - } - }, - "/subscriptions/{subscription_id}/migrations/preview.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Preview Subscription Product Migration", - "tags": [ - "Subscription Products" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Migration-Preview-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "migration": { - "prorated_adjustment_in_cents": 0, - "charge_in_cents": 5000, - "payment_due_in_cents": 0, - "credit_applied_in_cents": 0 - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Subscription must be active" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "previewSubscriptionProductMigration", - "description": "## Previewing a future date\nIt is also possible to preview the migration for a date in the future, as long as it's still within the subscription's current billing period, by passing a `proration_date` along with the request (eg: `\"proration_date\": \"2020-12-18T18:25:43.511Z\"`).\n\nThis will calculate the prorated adjustment, charge, payment and credit applied values assuming the migration is done at that date in the future as opposed to right now.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Migration-Preview-Request.yaml" - } - } - } - } - } - }, - "/subscriptions/{subscription_id}/override.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "put": { - "summary": "Override Subscription", - "tags": [ - "Subscriptions" - ], - "responses": { - "204": { - "description": "No Content" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Single-Error-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "error": "Current period starts at: must be a valid date/time" - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "overrideSubscription", - "description": "This API endpoint allows you to set certain subscription fields that are usually managed for you automatically. Some of the fields can be set via the normal Subscriptions Update API, but others can only be set using this endpoint.\n\nThis endpoint is provided for cases where you need to “align” Chargify data with data that happened in your system, perhaps before you started using Chargify. For example, you may choose to import your historical subscription data, and would like the activation and cancellation dates in Chargify to match your existing historical dates. Chargify does not backfill historical events (i.e. from the Events API), but some static data can be changed via this API.\n\nWhy are some fields only settable from this endpoint, and not the normal subscription create and update endpoints? Because we want users of this endpoint to be aware that these fields are usually managed by Chargify, and using this API means **you are stepping out on your own.**\n\nChanging these fields will not affect any other attributes. For example, adding an expiration date will not affect the next assessment date on the subscription.\n\nIf you regularly need to override the current_period_starts_at for new subscriptions, this can also be accomplished by setting both `previous_billing_at` and `next_billing_at` at subscription creation. See the documentation on [Importing Subscriptions](./b3A6MTQxMDgzODg-create-subscription#subscriptions-import) for more information.\n\n## Limitations\n\nWhen passing `current_period_starts_at` some validations are made:\n\n1. The subscription needs to be unbilled (no statements or invoices).\n2. The value passed must be a valid date/time. We recommend using the iso 8601 format.\n3. The value passed must be before the current date/time.\n\nIf unpermitted parameters are sent, a 400 HTTP response is sent along with a string giving the reason for the problem.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Override-Subscription-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "activated_at": "1999-12-01T10:28:34-05:00", - "canceled_at": "2000-12-31T10:28:34-05:00", - "cancellation_message": "Original cancellation in 2000", - "expires_at": "2001-07-15T10:28:34-05:00" - } - } - } - } - } - }, - "description": "Only these fields are available to be set." - } - } - }, - "/subscriptions/{subscription_id}/delayed_cancel.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Initiate Delayed Cancellation", - "tags": [ - "Subscription Status" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Delayed-Cancellation-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "initiateDelayedCancellation", - "description": "Chargify offers the ability to cancel a subscription at the end of the current billing period. This period is set by its current product.\n\nRequesting to cancel the subscription at the end of the period sets the `cancel_at_end_of_period` flag to true.\n\nNote that you cannot set `cancel_at_end_of_period` at subscription creation, or if the subscription is past due.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Cancellation-Request.yaml" - } - } - } - } - }, - "delete": { - "summary": "Cancel Delayed Cancellation", - "tags": [ - "Subscription Status" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Delayed-Cancellation-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "message": "This subscription will no longer be canceled" - } - } - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "cancelDelayedCancellation", - "description": "Removing the delayed cancellation on a subscription will ensure that it doesn't get canceled at the end of the period that it is in. The request will reset the `cancel_at_end_of_period` flag to `false`.\n\nThis endpoint is idempotent. If the subscription was not set to cancel in the future, removing the delayed cancellation has no effect and the call will be successful." - } - }, - "/subscriptions/{subscription_id}/cancel_dunning.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Cancel Dunning", - "tags": [ - "Subscription Status" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - } - } - } - } - }, - "operationId": "cancelDunning", - "description": "If a subscription is currently in dunning, the subscription will be set to active and the active Dunner will be resolved." - } - }, - "/subscriptions/{subscription_id}/renewals/preview.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Preview Renewal", - "tags": [ - "Subscription Status" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Renewal-Preview-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "renewal_preview": { - "next_assessment_at": "2017-03-13T12:50:55-04:00", - "subtotal_in_cents": 6000, - "total_tax_in_cents": 0, - "total_discount_in_cents": 0, - "total_in_cents": 6000, - "existing_balance_in_cents": 0, - "total_amount_due_in_cents": 6000, - "uncalculated_taxes": false, - "line_items": [ - { - "transaction_type": "charge", - "kind": "baseline", - "amount_in_cents": 5000, - "memo": "Gold Product (03/13/2017 - 04/13/2017)", - "discount_amount_in_cents": 0, - "taxable_amount_in_cents": 0, - "product_id": 1, - "product_handle": "gold-product", - "product_name": "Gold Product", - "period_range_start": "01/10/2024", - "period_range_end": "02/10/2024" - }, - { - "transaction_type": "charge", - "kind": "quantity_based_component", - "amount_in_cents": 1000, - "memo": "Quantity Component: 10 Quantity Components", - "discount_amount_in_cents": 0, - "taxable_amount_in_cents": 0, - "component_id": 104, - "component_handle": "quantity-component", - "component_name": "Quantity Component", - "period_range_start": "01/10/2024", - "period_range_end": "02/10/2024" - } - ] - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Couldn't find Component by handle:unknown" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "previewRenewal", - "description": "The Chargify API allows you to preview a renewal by posting to the renewals endpoint. Renewal Preview is an object representing a subscription’s next assessment. You can retrieve it to see a snapshot of how much your customer will be charged on their next renewal.\n\nThe \"Next Billing\" amount and \"Next Billing\" date are already represented in the UI on each Subscriber's Summary. For more information, please see our documentation [here](https://chargify.zendesk.com/hc/en-us/articles/4407884887835#next-billing).\n\n## Optional Component Fields\n\nThis endpoint is particularly useful due to the fact that it will return the computed billing amount for the base product and the components which are in use by a subscriber.\n\nBy default, the preview will include billing details for all components _at their **current** quantities_. This means:\n\n* Current `allocated_quantity` for quantity-based components\n* Current enabled/disabled status for on/off components\n* Current metered usage `unit_balance` for metered components\n* Current metric quantity value for events recorded thus far for events-based components\n\nIn the above statements, \"current\" means the quantity or value as of the call to the renewal preview endpoint. We do not predict end-of-period values for components, so metered or events-based usage may be less than it will eventually be at the end of the period.\n\nOptionally, **you may provide your own custom quantities** for any component to see a billing preview for non-current quantities. This is accomplished by sending a request body with data under the `components` key. See the request body documentation below.\n\n## Subscription Side Effects\n\nYou can request a `POST` to obtain this data from the endpoint without any side effects. Plain and simple, this will preview data, not log any changes against a subscription.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Renewal-Preview-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "components": [ - { - "component_id": 10708, - "quantity": 10000 - }, - { - "component_id": "handle:small-instance-hours", - "quantity": 10000, - "price_point_id": 8712 - }, - { - "component_id": "handle:large-instance-hours", - "quantity": 100, - "price_point_id": "handle:startup-pricing" - } - ] - } - } - } - } - }, - "description": "" - } - } - }, - "/subscriptions/{subscription_id}/invoices.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Create Invoice", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Invoice-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "invoice": { - "uid": "inv_98nbmb93gxjz8", - "site_id": 5, - "customer_id": 13, - "subscription_id": 17, - "number": "1", - "sequence_number": 1, - "issue_date": "2020-12-02", - "due_date": "2020-12-02", - "paid_date": null, - "status": "open", - "collection_method": "remittance", - "payment_instructions": "", - "currency": "USD", - "consolidation_level": "none", - "parent_invoice_uid": null, - "parent_invoice_number": null, - "group_primary_subscription_id": null, - "product_name": "Digitized discrete initiative", - "product_family_name": "Networked bottom-line orchestration", - "role": "adhoc", - "seller": { - "name": "Steuber, West and Hegmann 1", - "address": { - "street": null, - "line2": null, - "city": null, - "state": null, - "zip": null, - "country": null - }, - "phone": "(766) 316-0492" - }, - "customer": { - "chargify_id": 13, - "first_name": "Dean", - "last_name": "Adams", - "organization": null, - "email": "brandi1@example.com", - "vat_number": null, - "reference": null - }, - "memo": "", - "billing_address": { - "street": null, - "line2": null, - "city": null, - "state": null, - "zip": null, - "country": null - }, - "shipping_address": { - "street": null, - "line2": null, - "city": null, - "state": null, - "zip": null, - "country": null - }, - "subtotal_amount": "1800.0", - "discount_amount": "0.0", - "tax_amount": "0.0", - "total_amount": "1800.0", - "credit_amount": "0.0", - "paid_amount": "0.0", - "refund_amount": "0.0", - "due_amount": "1800.0", - "line_items": [ - { - "uid": "li_98nbmb9jgz84c", - "title": "Some product", - "description": "12/02/2020 - 12/02/2020", - "quantity": "12.0", - "unit_price": "150.0", - "subtotal_amount": "1800.0", - "discount_amount": "0.0", - "tax_amount": "0.0", - "total_amount": "1800.0", - "tiered_unit_price": false, - "period_range_start": "2020-12-02", - "period_range_end": "2020-12-02", - "product_id": null, - "product_version": null, - "product_price_point_id": null, - "component_id": null, - "price_point_id": null - } - ], - "discounts": [], - "taxes": [], - "credits": [], - "payments": [], - "refunds": [], - "custom_fields": [], - "public_url": "https://www.test-chargifypay.com/invoice/inv_98nbmb93gxjz8?token=rmfmwvbdy4xmyw5f29j5gc6x" - } - } - } - } - } - } - }, - "201": { - "description": "Created" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-Array-Map-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": { - "invoice": [ - "can't be blank" - ] - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createInvoice", - "description": "This endpoint will allow you to create an ad hoc invoice.\n\n### Basic Behavior\n\nYou can create a basic invoice by sending an array of line items to this endpoint. Each line item, at a minimum, must include a title, a quantity and a unit price. Example:\n\n```json\n{\n \"invoice\": {\n \"line_items\": [\n {\n \"title\": \"A Product\",\n \"quantity\": 12,\n \"unit_price\": \"150.00\"\n }\n ]\n }\n}\n```\n\n### Catalog items\nInstead of creating custom products like in above example, You can pass existing items like products, components.\n\n```json\n{\n \"invoice\": {\n \"line_items\": [\n {\n \"product_id\": \"handle:gold-product\",\n \"quantity\": 2,\n }\n ]\n }\n}\n```\n\n\nThe price for each line item will be calculated as well as a total due amount for the invoice. Multiple line items can be sent.\n\n### Line items types\nWhen defining line item, You can choose one of 3 types for one line item:\n#### Custom item\nLike in basic behavior example above, You can pass `title` and `unit_price` for custom item.\n#### Product id\nProduct handle (with handle: prefix) or id from the scope of current subscription's site can be provided with `product_id`. By default `unit_price` is taken from product's default price point, but can be overwritten by passing `unit_price` or `product_price_point_id`. If `product_id` is used, following fields cannot be used: `title`, `component_id`.\n#### Component id\nComponent handle (with handle: prefix) or id from the scope of current subscription's site can be provided with `component_id`. If `component_id` is used, following fields cannot be used: `title`, `product_id`. By default `unit_price` is taken from product's default price point, but can be overwritten by passing `unit_price` or `price_point_id`. At this moment price points are supportted only for quantity based, on/off and metered components. For prepaid and event based billing components `unit_price` is required.\n\n### Coupons\nWhen creating ad hoc invoice, new discounts can be applied in following way:\n\n```json\n{\n \"invoice\": {\n \"line_items\": [\n {\n \"product_id\": \"handle:gold-product\",\n \"quantity\": 1\n }\n ],\n \"coupons\": [\n {\n \"code\": \"COUPONCODE\",\n \"percentage\": 50.0\n }\n ]\n }\n}\n```\nIf You want to use existing coupon for discount creation, only `code` and optional `product_family_id` is needed\n\n```json\n...\n \"coupons\": [\n {\n \"code\": \"FREESETUP\",\n \"product_family_id\": 1\n }\n ]\n...\n```\n\n### Coupon options\n#### Code\nCoupon `code` will be displayed on invoice discount section.\nCoupon code can only contain uppercase letters, numbers, and allowed special characters.\nLowercase letters will be converted to uppercase. It can be used to select an existing coupon from the catalog, or as an ad hoc coupon when passed with `percentage` or `amount`.\n#### Percentage\nCoupon `percentage` can take values from 0 to 100 and up to 4 decimal places. It cannot be used with `amount`. Only for ad hoc coupons, will be ignored if `code` is used to select an existing coupon from the catalog.\n#### Amount\nCoupon `amount` takes number value. It cannot be used with `percentage`. Used only when not matching existing coupon by `code`.\n#### Description\nOptional `description` will be displayed with coupon `code`. Used only when not matching existing coupon by `code`.\n#### Product Family id\nOptional `product_family_id` handle (with handle: prefix) or id is used to match existing coupon within site, when codes are not unique.\n#### Compounding Strategy\nOptional `compounding_strategy` for percentage coupons, can take values `compound` or `full-price`.\n\nFor amount coupons, discounts will be always calculated against the original item price, before other discounts are applied.\n\n`compound` strategy:\nPercentage-based discounts will be calculated against the remaining price, after prior discounts have been calculated. It is set by default.\n\n`full-price` strategy:\nPercentage-based discounts will always be calculated against the original item price, before other discounts are applied.\n\n### Line Item Options\n\n#### Period Date Range\n\nA custom period date range can be defined for each line item with the `period_range_start` and `period_range_end` parameters. Dates must be sent in the `YYYY-MM-DD` format.\n`period_range_end` must be greater or equal `period_range_start`.\n\n#### Taxes\n\nThe `taxable` parameter can be sent as `true` if taxes should be calculated for a specific line item. For this to work, the site should be configured to use and calculate taxes. Further, if the site uses Avalara for tax calculations, a `tax_code` parameter should also be sent. For existing catalog items: products/components taxes cannot be overwritten.\n\n#### Price Point\nPrice point handle (with handle: prefix) or id from the scope of current subscription's site can be provided with `price_point_id` for components with `component_id` or `product_price_point_id` for products with `product_id` parameter. If price point is passed `unit_price` cannot be used. It can be used only with catalog items products and components.\n\n#### Description\nOptional `description` parameter, it will overwrite default generated description for line item.\n\n### Invoice Options\n\n#### Issue Date\n\nBy default, invoices will be created with a issue date set to today. `issue_date` parameter can be send to alter that. Only dates in the past can be send. `issue_date` should be send in `YYYY-MM-DD` format.\n\n#### Net Terms\n\nBy default, invoices will be created with a due date matching the date of invoice creation. If a different due date is desired, the `net_terms` parameter can be sent indicating the number of days in advance the due date should be.\n\n#### Addresses\n\nThe seller, shipping and billing addresses can be sent to override the site's defaults. Each address requires to send a `first_name` at a minimum in order to work. Please see below for the details on which parameters can be sent for each address object.\n\n#### Memo and Payment Instructions\n\nA custom memo can be sent with the `memo` parameter to override the site's default. Likewise, custom payment instructions can be sent with the `payment_instrucions` parameter.\n\n#### Status\n\nBy default, invoices will be created with open status. Possible alternative is `draft`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Invoice-Request.yaml" - }, - "examples": { - "Minimal Invoice (Relies on site defaults)": { - "value": { - "invoice": { - "line_items": [ - { - "title": "A Product", - "quantity": 12, - "unit_price": "150.00" - } - ] - } - } - }, - "Example": { - "value": { - "invoice": { - "line_items": [ - { - "title": "Widgets", - "quantity": 1, - "unit_price": "10.0", - "taxable": true, - "tax_code": "A1999", - "period_range_start": "2021-01-31", - "period_range_end": "2021-02-28" - } - ], - "net_terms": 20, - "payment_instructions": "Pay upon receipt", - "memo": "This is a memo", - "seller_address": { - "first_name": "string", - "last_name": "string", - "phone": "string", - "address": "string", - "address_2": "string", - "city": "string", - "state": "string", - "zip": "string", - "country": "string" - }, - "billing_address": { - "first_name": "string", - "last_name": "string", - "phone": "string", - "address": "string", - "address_2": "string", - "city": "string", - "state": "string", - "zip": "string", - "country": "string" - }, - "shipping_address": { - "first_name": "string", - "last_name": "string", - "phone": "string", - "address": "string", - "address_2": "string", - "city": "string", - "state": "string", - "zip": "string", - "country": "string" - } - } - } - } - } - } - }, - "description": "" - } - } - }, - "/subscriptions/{subscription_id}/prepayments.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Create Prepayment", - "tags": [ - "Subscription Invoice Account" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Prepayment-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "prepayment": { - "id": 1, - "subscription_id": 1, - "amount_in_cents": 10000, - "memo": "John Doe - Prepayment", - "created_at": "2020-07-31T05:52:32-04:00", - "starting_balance_in_cents": 0, - "ending_balance_in_cents": -10000 - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Create-Prepayment-Error-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "errors": { - "prepayment": "can't be blank" - } - } - }, - "Example-2": { - "value": { - "errors": [ - "Method: can't be blank", - "Memo: can't be blank", - "Details: can't be blank" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createPrepayment", - "description": "## Create Prepayment\n\nIn order to specify a prepayment made against a subscription, specify the `amount, memo, details, method`.\n\nWhen the `method` specified is `\"credit_card_on_file\"`, the prepayment amount will be collected using the default credit card payment profile and applied to the prepayment account balance. This is especially useful for manual replenishment of prepaid subscriptions.\n\nPlease note that you **can't** pass `amount_in_cents`.\n", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Prepayment-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "prepayment": { - "amount": 100, - "details": "John Doe signup for $100", - "memo": "Signup for $100", - "method": "check" - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Prepayments", - "tags": [ - "Subscription Invoice Account" - ], - "operationId": "listPrepayments", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Prepayments-Response.yaml" - }, - "examples": { - "example-success-response": { - "value": { - "prepayments": [ - { - "id": 17, - "subscription_id": 3558750, - "amount_in_cents": 2000, - "remaining_amount_in_cents": 1100, - "refunded_amount_in_cents": 0, - "external": true, - "memo": "test", - "details": "test details", - "payment_type": "cash", - "created_at": "2022-01-18T22:45:41+11:00" - } - ] - } - } - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "description": "This request will list a subscription's prepayments.", - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - }, - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "$ref": "../components/schemas/Basic-Date-Field.yaml" - }, - "in": "query", - "name": "filter[date_field]", - "description": "The type of filter you would like to apply to your search. created_at - Time when prepayment was created. application_at - Time when prepayment was applied to invoice. Use in query `filter[date_field]=created_at`." - }, - { - "schema": { - "type": "string", - "format": "date", - "example": "2011-12-15" - }, - "in": "query", - "name": "filter[start_date]", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns prepayments with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. Use in query `filter[start_date]=2011-12-15`." - }, - { - "schema": { - "type": "string", - "format": "date", - "example": "2011-12-15" - }, - "in": "query", - "name": "filter[end_date]", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns prepayments with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. Use in query `filter[end_date]=2011-12-15`." - } - ] - } - }, - "/subscriptions/{subscription_id}/service_credits.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Issue Service Credit", - "tags": [ - "Subscription Invoice Account" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Service-Credit.yaml" - }, - "examples": { - "Example": { - "value": { - "id": 101, - "amount_in_cents": 1000, - "ending_balance_in_cents": 2000, - "entry_type": "Credit", - "memo": "Credit to group account" - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Issue-Service-Credit-Error-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "errors": { - "service_credit": "can't be blank" - } - } - }, - "Example-2": { - "value": { - "errors": [ - "Amount must be greater than 0" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "issueServiceCredit", - "description": "Credit will be added to the subscription in the amount specified in the request body. The credit is subsequently applied to the next generated invoice.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Issue-Service-Credit-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "service_credit": { - "amount": "1", - "memo": "Courtesy credit" - } - } - } - } - } - } - } - } - }, - "/subscriptions/{subscription_id}/service_credit_deductions.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Deduct Service Credit", - "tags": [ - "Subscription Invoice Account" - ], - "responses": { - "200": { - "description": "OK" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Deduct-Service-Credit-Error-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "errors": { - "deduction": "can't be blank" - } - } - }, - "Example-2": { - "value": { - "errors": [ - "Amount must be greater than 0." - ] - } - }, - "Example-3": { - "value": { - "errors": [ - "Amount cannot exceed current service credit account balance." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "deductServiceCredit", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Deduct-Service-Credit-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "deduction": { - "amount": "1", - "memo": "Deduction" - } - } - } - } - } - } - }, - "description": "Credit will be removed from the subscription in the amount specified in the request body. The credit amount being deducted must be equal to or less than the current credit balance." - } - }, - "/subscription_groups/signup.json": { - "post": { - "operationId": "signupWithSubscriptionGroup", - "summary": "Subscription Group Signup", - "description": "Create multiple subscriptions at once under the same customer and consolidate them into a subscription group.\n\nYou must provide one and only one of the `payer_id`/`payer_reference`/`payer_attributes` for the customer attached to the group.\n\nYou must provide one and only one of the `payment_profile_id`/`credit_card_attributes`/`bank_account_attributes` for the payment profile attached to the group.\n\nOnly one of the `subscriptions` can have `\"primary\": true` attribute set.\n\nWhen passing product to a subscription you can use either `product_id` or `product_handle` or `offer_id`. You can also use `custom_price` instead.", - "tags": [ - "Subscription Groups" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Group-Signup-Response.yaml" - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Subscription-Group-Signup-Error-Response.yaml" - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Group-Signup-Request.yaml" - }, - "examples": { - "Basic request": { - "value": { - "subscription_group": { - "payment_profile_id": 123, - "payer_id": 123, - "subscriptions": [ - { - "product_id": 11, - "primary": true - }, - { - "product_id": 12 - }, - { - "product_id": 13 - } - ] - } - } - }, - "Create customer and payment profile in-place": { - "value": { - "subscription_group": { - "payer_attributes": { - "first_name": "John", - "last_name": "Doe", - "email": "john@example.com", - "organization": "Acme, Inc" - }, - "credit_card_attributes": { - "full_number": "4111111111111111", - "expiration_month": "12", - "expiration_year": "2031" - }, - "subscriptions": [ - { - "product_id": 123, - "primary": true - }, - { - "product_handle": "silver-plan" - }, - { - "product_id": 124 - } - ] - } - } - }, - "Create credit card using Chargify.js token": { - "value": { - "subscription_group": { - "payer_id": 123, - "credit_card_attributes": { - "chargify_token": "tok_19gnjsa9433u9b22", - "last_four": "1111", - "card_type": "visa" - }, - "subscriptions": [ - { - "product_id": 11, - "primary": true - }, - { - "product_id": 12 - }, - { - "product_id": 13 - } - ] - } - } - }, - "Create bank account using Chargify.js token": { - "value": { - "subscription_group": { - "payer_id": 234, - "bank_account_attributes": { - "chargify_token": "tok_19gnjsa9433u9b22" - }, - "subscriptions": [ - { - "product_id": 11, - "primary": true - }, - { - "product_id": 12 - }, - { - "product_id": 13 - } - ] - } - } - }, - "Create group with subscription and customer metafields": { - "value": { - "subscription_group": { - "payer_attributes": { - "first_name": "John", - "last_name": "Doe", - "email": "john@example.com", - "organization": "Acme, Inc", - "metafields": { - "win-over": "ABCompany" - } - }, - "credit_card_attributes": { - "full_number": "4111111111111111", - "expiration_month": "12", - "expiration_year": "2031" - }, - "subscriptions": [ - { - "product_id": 123, - "primary": true, - "metafields": { - "mrr": "$99", - "discounted": "false" - } - }, - { - "product_handle": "silver-plan", - "metafields": { - "mrr": "$49" - } - }, - { - "product_id": 124 - } - ] - } - } - }, - "Create subscription with components": { - "value": { - "subscription_group": { - "payment_profile_id": 123, - "payer_id": 123, - "subscriptions": [ - { - "product_id": 11, - "primary": true, - "components": [ - { - "component_id": 99, - "allocated_quantity": 10 - } - ] - }, - { - "product_id": 12 - }, - { - "product_id": 13 - } - ] - } - } - }, - "Create subscription with Custom Pricing": { - "value": { - "subscription_group": { - "payment_profile_id": 123, - "payer_id": 123, - "subscriptions": [ - { - "product_id": 19, - "custom_price": { - "handle": "custom-price", - "price_in_cents": 9900, - "interval": 1, - "interval_unit": "month" - }, - "primary": true - }, - { - "product_id": 12, - "components": [ - { - "component_id": 29, - "allocated_quantity": 5, - "custom_price": { - "pricing_scheme": "volume", - "prices": [ - { - "unit_price": "5", - "starting_quantity": "1", - "ending_quantity": "15" - }, - { - "unit_price": "2", - "starting_quantity": "16" - } - ] - } - } - ] - }, - { - "product_id": 13 - } - ] - } - } - } - } - } - } - } - }, - "parameters": [] - }, - "/subscription_groups.json": { - "post": { - "summary": "Create Subscription Group", - "tags": [ - "Subscription Groups" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Group-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription_group": { - "customer_id": 1, - "payment_profile": { - "id": 1, - "first_name": "t", - "last_name": "t", - "masked_card_number": "XXXX-XXXX-XXXX-1" - }, - "payment_collection_method": "automatic", - "subscription_ids": [ - 1, - 2 - ], - "created_at": "2021-01-21T05:47:38-05:00" - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Single-String-Error-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": "Subscription is already in group" - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createSubscriptionGroup", - "description": "Creates a subscription group with given members.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Subscription-Group-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription_group": { - "subscription_id": 1, - "member_ids": [ - 2, - 3, - 4 - ] - } - } - } - } - } - } - } - }, - "get": { - "summary": "List Subscription Groups", - "tags": [ - "Subscription Groups" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Subscription-Groups-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription_groups": [ - { - "uid": "grp_952mvqcnk53wq", - "scheme": 1, - "customer_id": 88498000, - "payment_profile_id": 93063018, - "subscription_ids": [ - 42768907, - 82370782 - ], - "primary_subscription_id": 69844395, - "next_assessment_at": "2021-05-05T16:00:21-04:00", - "state": "active", - "cancel_at_end_of_period": false, - "account_balances": { - "prepayments": { - "balance_in_cents": 0 - }, - "service_credits": { - "balance_in_cents": 0 - }, - "pending_discounts": { - "balance_in_cents": 0 - } - } - } - ], - "meta": { - "current_page": 1, - "total_count": 1 - } - } - } - } - } - } - } - }, - "operationId": "listSubscriptionGroups", - "description": "Returns an array of subscription groups for the site. The response is paginated and will return a `meta` key with pagination information.\n\n#### Account Balance Information\n\nAccount balance information for the subscription groups is not returned by default. If this information is desired, the `include[]=account_balances` parameter must be provided with the request.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "include", - "description": "A list of additional information to include in the response. The following values are supported:\n\n- `account_balances`: Account balance information for the subscription groups. Use in query: `include[]=account_balances`" - } - ] - } - }, - "/subscription_groups/{uid}.json": { - "parameters": [ - { - "$ref": "../components/parameters/group-uid-path.yaml" - } - ], - "get": { - "summary": "Read Subscription Group", - "tags": [ - "Subscription Groups" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Full-Subscription-Group-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "uid": "grp_939ktzq8v4477", - "scheme": 1, - "customer_id": 400, - "payment_profile_id": 567, - "subscription_ids": [ - 101, - 102, - 103 - ], - "primary_subscription_id": 101, - "next_assessment_at": "2020-08-01T14:00:00-05:00", - "state": "active", - "cancel_at_end_of_period": false, - "current_billing_amount_in_cents": 11500, - "customer": { - "first_name": "Mark", - "last_name": "Wannabewahlberg", - "organization": "The Funky Bunch", - "email": "markymark@example.com", - "reference": "4c92223b-bc16-4d0d-87ff-b177a89a2655" - }, - "account_balances": { - "prepayments": { - "balance_in_cents": 0 - }, - "service_credits": { - "balance_in_cents": 0 - }, - "open_invoices": { - "balance_in_cents": 4400 - }, - "pending_discounts": { - "balance_in_cents": 0 - } - } - } - } - } - } - } - } - }, - "operationId": "readSubscriptionGroup", - "description": "Use this endpoint to find subscription group details.\n\n#### Current Billing Amount in Cents\n\nCurrent billing amount for the subscription group is not returned by default. If this information is desired, the `include[]=current_billing_amount_in_cents` parameter must be provided with the request." - }, - "put": { - "summary": "Update Subscription Group Members", - "tags": [ - "Subscription Groups" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Group-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription_group": { - "customer_id": 1, - "payment_profile": { - "id": 1, - "first_name": "t", - "last_name": "t", - "masked_card_number": "XXXX-XXXX-XXXX-1" - }, - "payment_collection_method": "automatic", - "subscription_ids": [ - 1 - ], - "created_at": "2021-01-21T05:47:38-05:00" - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Subscription-Group-Update-Error-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": { - "members": [ - { - "id": 10101, - "type": "not_found", - "message": "Subscription could not be found" - } - ] - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updateSubscriptionGroupMembers", - "description": "Use this endpoint to update subscription group members.\n`\"member_ids\": []` should contain an array of both subscription IDs to set as group members and subscription IDs already present in the groups. Not including them will result in removing them from subscription group. To clean up members, just leave the array empty.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Subscription-Group-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription_group": { - "member_ids": [ - 1, - 2, - 3 - ] - } - } - } - } - } - } - } - }, - "delete": { - "summary": "Delete Subscription Group", - "tags": [ - "Subscription Groups" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Delete-Subscription-Group-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "uid": "grp_99w5xp9y5xycy", - "deleted": true - } - } - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "deleteSubscriptionGroup", - "description": "Use this endpoint to delete subscription group.\nOnly groups without members can be deleted" - } - }, - "/subscription_groups/lookup.json": { - "get": { - "summary": "Find Subscription Group", - "tags": [ - "Subscription Groups" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Full-Subscription-Group-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "uid": "grp_939ktzq8v4477", - "scheme": 1, - "customer_id": 400, - "payment_profile_id": 567, - "subscription_ids": [ - 101, - 102, - 103 - ], - "primary_subscription_id": 101, - "next_assessment_at": "2020-08-01T14:00:00-05:00", - "state": "active", - "cancel_at_end_of_period": false, - "customer": { - "first_name": "Mark", - "last_name": "Wannabewahlberg", - "organization": "The Funky Bunch", - "email": "markymark@example.com", - "reference": "4c92223b-bc16-4d0d-87ff-b177a89a2655" - }, - "account_balances": { - "prepayments": { - "balance_in_cents": 0 - }, - "service_credits": { - "balance_in_cents": 0 - }, - "open_invoices": { - "balance_in_cents": 4400 - }, - "pending_discounts": { - "balance_in_cents": 0 - } - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "findSubscriptionGroup", - "description": "Use this endpoint to find subscription group associated with subscription.\n\nIf the subscription is not in a group endpoint will return 404 code.", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "subscription_id", - "required": true, - "description": "The Chargify id of the subscription associated with the subscription group" - } - ] - } - }, - "/subscription_groups/{uid}/cancel.json": { - "parameters": [ - { - "$ref": "../components/parameters/group-uid-path.yaml" - } - ], - "post": { - "summary": "Cancel Grouped Subscriptions", - "tags": [ - "Subscription Group Status" - ], - "responses": { - "200": { - "description": "OK" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "One or more subscriptions are not on automatic billing" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "cancelSubscriptionsInGroup", - "description": "This endpoint will immediately cancel all subscriptions within the specified group. The group is identified by it's `uid` passed in the URL. To successfully cancel the group, the primary subscription must be on automatic billing. The group members as well must be on automatic billing or they must be prepaid.\n\nIn order to cancel a subscription group while also charging for any unbilled usage on metered or prepaid components, the `charge_unbilled_usage=true` parameter must be included in the request.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Cancel-Grouped-Subscriptions-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "charge_unbilled_usage": true - } - } - } - } - } - } - } - }, - "/subscription_groups/{uid}/delayed_cancel.json": { - "parameters": [ - { - "$ref": "../components/parameters/group-uid-path.yaml" - } - ], - "post": { - "summary": "Initiate Delayed Group Cancellation", - "tags": [ - "Subscription Group Status" - ], - "responses": { - "200": { - "description": "OK" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Subscriptions group is in a past due state" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "initiateDelayedCancellationForGroup", - "description": "This endpoint will schedule all subscriptions within the specified group to be canceled at the end of their billing period. The group is identified by it's uid passed in the URL.\n\nAll subscriptions in the group must be on automatic billing in order to successfully cancel them, and the group must not be in a \"past_due\" state." - }, - "delete": { - "summary": "Cancel Delayed Group Cancellation", - "tags": [ - "Subscription Group Status" - ], - "responses": { - "200": { - "description": "OK" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Subscriptions group does not have a pending delayed cancellation" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "cancelDelayedCancellationForGroup", - "description": "Removing the delayed cancellation on a subscription group will ensure that the subscriptions do not get canceled at the end of the period. The request will reset the `cancel_at_end_of_period` flag to false on each member in the group." - } - }, - "/subscription_groups/{uid}/reactivate.json": { - "parameters": [ - { - "$ref": "../components/parameters/group-uid-path.yaml" - } - ], - "post": { - "summary": "Reactivate / Resume Subscription Group", - "tags": [ - "Subscription Group Status" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Reactivate-Subscription-Group-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "uid": "grp_93wgm89cbjkw6", - "scheme": 1, - "customer_id": 1, - "payment_profile_id": 1, - "subscription_ids": [ - 1, - 2 - ], - "primary_subscription_id": 1, - "next_assessment_at": "2020-06-18T12:00:00-04:00", - "state": "active", - "cancel_at_end_of_period": false - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Must be inside the current billing period to resume this subscription group" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "reactivateSubscriptionGroup", - "description": "This endpoint will attempt to reactivate or resume a cancelled subscription group. Upon reactivation, any canceled invoices created after the beginning of the primary subscription's billing period will be reopened and payment will be attempted on them. If the subscription group is being reactivated (as opposed to resumed), new charges will also be assessed for the new billing period.\n\nWhether a subscription group is reactivated (a new billing period is created) or resumed (the current billing period is respected) will depend on the parameters that are sent with the request as well as the date of the request relative to the primary subscription's period.\n\n## Reactivating within the current period\n\nIf a subscription group is cancelled and reactivated within the primary subscription's current period, we can choose to either start a new billing period or maintain the existing one. If we want to maintain the existing billing period the `resume=true` option must be passed in request parameters.\n\nAn exception to the above are subscriptions that are on calendar billing. These subscriptions cannot be reactivated within the current period. If the `resume=true` option is not passed the request will return an error.\n\nThe `resume_members` option is ignored in this case. All eligible group members will be automatically resumed.\n\n\n## Reactivating beyond the current period\n\nIn this case, a subscription group can only be reactivated with a new billing period. If the `resume=true` option is passed it will be ignored.\n\nMember subscriptions can have billing periods that are longer than the primary (e.g. a monthly primary with annual group members). If the primary subscription in a group cannot be reactivated within the current period, but other group members can be, passing `resume_members=true` will resume the existing billing period for eligible group members. The primary subscription will begin a new billing period.\n\nFor calendar billing subscriptions, the new billing period created will be a partial one, spanning from the date of reactivation to the next corresponding calendar renewal date.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Reactivate-Subscription-Group-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "resume": true - } - } - } - } - } - } - } - }, - "/subscription_groups/{uid}/payment_profiles/{payment_profile_id}.json": { - "parameters": [ - { - "$ref": "../components/parameters/group-uid-path.yaml" - }, - { - "$ref": "../components/parameters/payment-profile-id-path.yaml" - } - ], - "delete": { - "summary": "Delete Subscription Group Payment Profile", - "responses": { - "204": { - "description": "No Content" - } - }, - "operationId": "deleteSubscriptionGroupPaymentProfile", - "description": "This will delete a Payment Profile belonging to a Subscription Group.\n\n**Note**: If the Payment Profile belongs to multiple Subscription Groups and/or Subscriptions, it will be removed from all of them.", - "tags": [ - "Payment Profiles" - ] - } - }, - "/subscription_groups/{uid}/prepayments.json": { - "parameters": [ - { - "$ref": "../components/parameters/group-uid-path.yaml" - } - ], - "post": { - "summary": "Create Subscription Group Prepayment", - "tags": [ - "Subscription Group Invoice Account" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Group-Prepayment-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "id": 6049554, - "amount_in_cents": 10000, - "ending_balance_in_cents": 5000, - "entry_type": "Debit", - "memo": "Debit from invoice account." - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Amount must be greater than 0" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createSubscriptionGroupPrepayment", - "description": "A prepayment can be added for a subscription group identified by the group's `uid`. This endpoint requires a `amount`, `details`, `method`, and `memo`. On success, the prepayment will be added to the group's prepayment balance.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Group-Prepayment-Request.yaml" - } - } - } - } - }, - "get": { - "summary": "List Prepayments For Subscription Group", - "tags": [ - "Subscription Group Invoice Account" - ], - "operationId": "listPrepaymentsForSubscriptionGroup", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Subscription-Group-Prepayment-Response.yaml" - }, - "examples": { - "example-success-response": { - "value": { - "prepayments": [ - { - "prepayment": { - "id": 142, - "subscription_group_uid": "grp_b4qhx3bvx72t8", - "amount_in_cents": 10000, - "remaining_amount_in_cents": 10000, - "details": "test", - "external": true, - "memo": "test", - "payment_type": "cash", - "created_at": "2023-06-21T04:37:02-04:00" - } - } - ] - } - } - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "security": [ - { - "BasicAuth": [] - } - ], - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - }, - "collectParameters": true - }, - "parameters": [ - { - "schema": { - "$ref": "../components/schemas/List-Subscription-Group-Prepayment-Date-Field.yaml" - }, - "in": "query", - "name": "filter[date_field]", - "description": "The type of filter you would like to apply to your search.\nUse in query: `filter[date_field]=created_at`." - }, - { - "schema": { - "type": "string", - "format": "date", - "example": "2011-12-15" - }, - "in": "query", - "name": "filter[end_date]", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field.\nReturns prepayments with a timestamp up to and including 11:59:59PM in your site's time zone on the date specified.\nUse in query: `filter[end_date]=2011-12-15`." - }, - { - "schema": { - "type": "string", - "format": "date", - "example": "2011-12-15" - }, - "in": "query", - "name": "filter[start_date]", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field.\nReturns prepayments with a timestamp at or after midnight (12:00:00 AM) in your site's time zone on the date specified.\nUse in query: `filter[start_date]=2011-12-15`." - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - } - ], - "description": "This request will list a subscription group's prepayments." - } - }, - "/subscription_groups/{uid}/service_credits.json": { - "parameters": [ - { - "$ref": "../components/parameters/group-uid-path.yaml" - } - ], - "post": { - "summary": "Issue Subscription Group Service Credit", - "tags": [ - "Subscription Group Invoice Account" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Service-Credit-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "service_credit": { - "id": 101, - "amount_in_cents": 1000, - "ending_balance_in_cents": 2000, - "entry_type": "Credit", - "memo": "Credit to group account" - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Amount must be greater than 0" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "issueSubscriptionGroupServiceCredit", - "description": "Credit can be issued for a subscription group identified by the group's `uid`. Credit will be added to the group in the amount specified in the request body. The credit will be applied to group member invoices as they are generated.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Issue-Service-Credit-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "service_credit": { - "amount": 10, - "memo": "Credit the group account" - } - } - } - } - } - } - } - } - }, - "/subscription_groups/{uid}/service_credit_deductions.json": { - "parameters": [ - { - "$ref": "../components/parameters/group-uid-path.yaml" - } - ], - "post": { - "summary": "Deduct Subscription Group Service Credit", - "tags": [ - "Subscription Group Invoice Account" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Service-Credit.yaml" - }, - "examples": { - "Example": { - "value": { - "id": 100, - "amount_in_cents": 1000, - "ending_balance_in_cents": 0, - "entry_type": "Debit", - "memo": "Debit from group account" - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Amount must be greater than 0" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "deductSubscriptionGroupServiceCredit", - "description": "Credit can be deducted for a subscription group identified by the group's `uid`. Credit will be deducted from the group in the amount specified in the request body.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Deduct-Service-Credit-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "deduction": { - "amount": 10, - "memo": "Deduct from group account" - } - } - } - } - } - } - } - } - }, - "/subscriptions/lookup.json": { - "get": { - "summary": "Find Subscription", - "tags": [ - "Subscriptions" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - } - } - } - } - }, - "operationId": "findSubscription", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "reference", - "description": "Subscription reference" - } - ], - "description": "Use this endpoint to find a subscription by its reference." - } - }, - "/subscriptions/{subscription_id}/payment_profiles/{payment_profile_id}/change_payment_profile.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - }, - { - "$ref": "../components/parameters/payment-profile-id-path.yaml" - } - ], - "post": { - "summary": "Change Subscription Default Payment Profile", - "tags": [ - "Payment Profiles" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Payment-Profile-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "payment_profile": { - "id": 10211899, - "first_name": "Amelia", - "last_name": "Example", - "masked_card_number": "XXXX-XXXX-XXXX-1", - "card_type": "bogus", - "expiration_month": 2, - "expiration_year": 2018, - "customer_id": 14399371, - "current_vault": "bogus", - "vault_token": "1", - "billing_address": "", - "billing_city": "", - "billing_state": "", - "billing_zip": "", - "billing_country": "", - "customer_vault_token": null, - "billing_address_2": "", - "payment_type": "credit_card", - "site_gateway_setting_id": 1, - "gateway_handle": null - } - } - } - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "This is already the current payment profile" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "changeSubscriptionDefaultPaymentProfile", - "description": "This will change the default payment profile on the subscription to the existing payment profile with the id specified.\n\nYou must elect to change the existing payment profile to a new payment profile ID in order to receive a satisfactory response from this endpoint." - } - }, - "/subscription_groups/{uid}/payment_profiles/{payment_profile_id}/change_payment_profile.json": { - "parameters": [ - { - "$ref": "../components/parameters/group-uid-path.yaml" - }, - { - "$ref": "../components/parameters/payment-profile-id-path.yaml" - } - ], - "post": { - "summary": "Change Subscription Group Default Payment Profile", - "tags": [ - "Payment Profiles" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Payment-Profile-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "payment_profile": { - "id": 10211899, - "first_name": "Amelia", - "last_name": "Example", - "masked_card_number": "XXXX-XXXX-XXXX-1", - "card_type": "bogus", - "expiration_month": 2, - "expiration_year": 2018, - "customer_id": 14399371, - "current_vault": "bogus", - "vault_token": "1", - "billing_address": "", - "billing_city": "", - "billing_state": "", - "billing_zip": "", - "billing_country": "", - "customer_vault_token": null, - "billing_address_2": "", - "payment_type": "credit_card", - "site_gateway_setting_id": 1, - "gateway_handle": null - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "This is already the current payment profile" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "changeSubscriptionGroupDefaultPaymentProfile", - "description": "This will change the default payment profile on the subscription group to the existing payment profile with the id specified.\n\nYou must elect to change the existing payment profile to a new payment profile ID in order to receive a satisfactory response from this endpoint.\n\nThe new payment profile must belong to the subscription group's customer, otherwise you will receive an error." - } - }, - "/subscriptions/{subscription_id}/purge.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Purge Subscription", - "tags": [ - "Subscriptions" - ], - "responses": { - "200": { - "description": "OK" - } - }, - "operationId": "purgeSubscription", - "description": "For sites in test mode, you may purge individual subscriptions.\n\nProvide the subscription ID in the url. To confirm, supply the customer ID in the query string `ack` parameter. You may also delete the customer record and/or payment profiles by passing `cascade` parameters. For example, to delete just the customer record, the query params would be: `?ack={customer_id}&cascade[]=customer`\n\nIf you need to remove subscriptions from a live site, please contact support to discuss your use case.\n\n### Delete customer and payment profile\n\nThe query params will be: `?ack={customer_id}&cascade[]=customer&cascade[]=payment_profile`", - "parameters": [ - { - "schema": { - "type": "integer" - }, - "in": "query", - "name": "ack", - "description": "id of the customer.", - "required": true - }, - { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Subscription-Purge-Type.yaml" - }, - "example": [ - "customer", - "payment_profile" - ] - }, - "in": "query", - "name": "cascade[]", - "style": "form", - "explode": true, - "description": "Options are \"customer\" or \"payment_profile\".\nUse in query: `cascade[]=customer&cascade[]=payment_profile`." - } - ] - } - }, - "/subscriptions/{subscription_id}/prepaid_configurations.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Update Prepaid Subscription Configuration", - "tags": [ - "Subscriptions" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Prepaid-Configuration-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "prepaid_configuration": { - "id": 55, - "initial_funding_amount_in_cents": 2500, - "auto_replenish": true, - "replenish_to_amount_in_cents": 50000, - "replenish_threshold_amount_in_cents": 10000 - } - } - } - } - } - } - } - }, - "operationId": "updatePrepaidSubscriptionConfiguration", - "description": "Use this endpoint to update a subscription's prepaid configuration.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Upsert-Prepaid-Configuration-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "prepaid_configuration": { - "initial_funding_amount_in_cents": 50000, - "replenish_to_amount_in_cents": 50000, - "auto_replenish": true, - "replenish_threshold_amount_in_cents": 10000 - } - } - } - } - } - } - } - } - }, - "/subscriptions/{subscription_id}/group.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Add Subscription to Group", - "tags": [ - "Subscription Groups" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Group-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription_group": { - "customer_id": 130690, - "payment_profile": { - "id": 32055, - "first_name": "Marty", - "last_name": "McFly", - "masked_card_number": "XXXX-XXXX-XXXX-1111" - }, - "subscription_ids": [ - 32988, - 33060, - 32986 - ], - "created_at": "2018-08-30T17:14:30-04:00" - } - } - } - } - } - } - } - }, - "operationId": "addSubscriptionToGroup", - "description": "For sites making use of the [Relationship Billing](https://chargify.zendesk.com/hc/en-us/articles/4407737494171) and [Customer Hierarchy](https://chargify.zendesk.com/hc/en-us/articles/4407746683291) features, it is possible to add existing subscriptions to subscription groups.\n\nPassing `group` parameters with a `target` containing a `type` and optional `id` is all that's needed. When the `target` parameter specifies a `\"customer\"` or `\"subscription\"` that is already part of a hierarchy, the subscription will become a member of the customer's subscription group. If the target customer or subscription is not part of a subscription group, a new group will be created and the subscription will become part of the group with the specified target customer set as the responsible payer for the group's subscriptions.\n\n**Please Note:** In order to add an existing subscription to a subscription group, it must belong to either the same customer record as the target, or be within the same customer hierarchy.\n\nRather than specifying a customer, the `target` parameter could instead simply have a value of\n* `\"self\"` which indicates the subscription will be paid for not by some other customer, but by the subscribing customer,\n* `\"parent\"` which indicates the subscription will be paid for by the subscribing customer's parent within a customer hierarchy, or\n* `\"eldest\"` which indicates the subscription will be paid for by the root-level customer in the subscribing customer's hierarchy.\n\nTo create a new subscription into a subscription group, please reference the following:\n[Create Subscription in a Subscription Group](https://developers.chargify.com/docs/api-docs/d571659cf0f24-create-subscription#subscription-in-a-subscription-group)\n", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Add-To-Group-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "group": { - "target": { - "type": "subscription", - "id": 32987 - }, - "billing": { - "accrue": true, - "align_date": true, - "prorate": true - } - } - } - } - } - } - } - } - }, - "delete": { - "summary": "Remove Subscription from Group", - "tags": [ - "Subscription Groups" - ], - "responses": { - "204": { - "description": "No Content" - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "You can not remove primary subscription when there are others in group" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "removeSubscriptionFromGroup", - "description": "For sites making use of the [Relationship Billing](https://chargify.zendesk.com/hc/en-us/articles/4407737494171) and [Customer Hierarchy](https://chargify.zendesk.com/hc/en-us/articles/4407746683291) features, it is possible to remove existing subscription from subscription group." - } - }, - "/subscriptions/preview.json": { - "post": { - "summary": "Preview Subscription", - "tags": [ - "Subscriptions" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Preview-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription_preview": { - "current_billing_manifest": { - "line_items": [ - { - "transaction_type": "charge", - "kind": "baseline", - "amount_in_cents": 5000, - "memo": "Gold Product (08/21/2018 - 09/21/2018)", - "discount_amount_in_cents": 0, - "taxable_amount_in_cents": 0, - "product_id": 1, - "product_handle": "gold-product", - "product_name": "Gold Product", - "period_range_start": "13 Oct 2023", - "period_range_end": "13 Nov 2023" - }, - { - "transaction_type": "charge", - "kind": "component", - "amount_in_cents": 28000, - "memo": "Component name: 14 Unit names", - "discount_amount_in_cents": 0, - "taxable_amount_in_cents": 0, - "component_id": 462149, - "component_handle": "handle", - "component_name": "Component name" - }, - { - "transaction_type": "charge", - "kind": "component", - "amount_in_cents": 2000, - "memo": "Fractional Metered Components: 20.0 Fractional Metereds", - "discount_amount_in_cents": 0, - "taxable_amount_in_cents": 0, - "component_id": 426665, - "component_handle": "handle", - "component_name": "Fractional Metered Components" - }, - { - "transaction_type": "charge", - "kind": "component", - "amount_in_cents": 0, - "memo": "On/Off Component", - "discount_amount_in_cents": 0, - "taxable_amount_in_cents": 0, - "component_id": 426670, - "component_handle": "handle", - "component_name": "On/Off Component" - }, - { - "transaction_type": "adjustment", - "kind": "coupon", - "amount_in_cents": 0, - "memo": "Coupon: 1DOLLAR - You only get $1.00 off", - "discount_amount_in_cents": 0, - "taxable_amount_in_cents": 0 - } - ], - "total_in_cents": 35000, - "total_discount_in_cents": 0, - "total_tax_in_cents": 0, - "subtotal_in_cents": 35000, - "start_date": "2018-08-21T21:25:21Z", - "end_date": "2018-09-21T21:25:21Z", - "period_type": "recurring", - "existing_balance_in_cents": 0 - }, - "next_billing_manifest": { - "line_items": [ - { - "transaction_type": "charge", - "kind": "baseline", - "amount_in_cents": 5000, - "memo": "Gold Product (09/21/2018 - 10/21/2018)", - "discount_amount_in_cents": 0, - "taxable_amount_in_cents": 0, - "product_id": 1, - "product_handle": "gold-product", - "product_name": "Gold Product" - }, - { - "transaction_type": "charge", - "kind": "component", - "amount_in_cents": 28000, - "memo": "Component name: 14 Unit names", - "discount_amount_in_cents": 0, - "taxable_amount_in_cents": 0, - "component_id": 462149, - "component_handle": "handle", - "component_name": "Component name" - }, - { - "transaction_type": "charge", - "kind": "component", - "amount_in_cents": 0, - "memo": "On/Off Component", - "discount_amount_in_cents": 0, - "taxable_amount_in_cents": 0, - "component_id": 426670, - "component_handle": "handle", - "component_name": "On/Off Component" - } - ], - "total_in_cents": 33000, - "total_discount_in_cents": 0, - "total_tax_in_cents": 0, - "subtotal_in_cents": 33000, - "start_date": "2018-09-21T21:25:21Z", - "end_date": "2018-10-21T21:25:21Z", - "period_type": "recurring", - "existing_balance_in_cents": 0 - } - } - } - } - } - } - } - } - }, - "operationId": "previewSubscription", - "description": "The Chargify API allows you to preview a subscription by POSTing the same JSON or XML as for a subscription creation.\n\nThe \"Next Billing\" amount and \"Next Billing\" date are represented in each Subscriber's Summary. For more information, please see our documentation [here](https://chargify.zendesk.com/hc/en-us/articles/4407884887835#next-billing).\n\n## Side effects\n\nA subscription will not be created by sending a POST to this endpoint. It is meant to serve as a prediction.\n\n## Taxable Subscriptions\n\nThis endpoint will preview taxes applicable to a purchase. In order for taxes to be previewed, the following conditions must be met:\n\n+ Taxes must be configured on the subscription\n+ The preview must be for the purchase of a taxable product or component, or combination of the two.\n+ The subscription payload must contain a full billing or shipping address in order to calculate tax\n\nFor more information about creating taxable previews, please see our documentation guide on how to create [taxable subscriptions.](https://chargify.zendesk.com/hc/en-us/articles/4407904217755#creating-taxable-subscriptions)\n\nYou do **not** need to include a card number to generate tax information when you are previewing a subscription. However, please note that when you actually want to create the subscription, you must include the credit card information if you want the billing address to be stored in Chargify. The billing address and the credit card information are stored together within the payment profile object. Also, you may not send a billing address to Chargify without payment profile information, as the address is stored on the card.\n\nYou can pass shipping and billing addresses and still decide not to calculate taxes. To do that, pass `skip_billing_manifest_taxes: true` attribute.\n\n## Non-taxable Subscriptions\n\nIf you'd like to calculate subscriptions that do not include tax, please feel free to leave off the billing information.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Subscription-Request.yaml" - }, - "examples": { - "Product Only": { - "value": { - "subscription": { - "product_handle": "gold-product" - } - } - }, - "With Components": { - "value": { - "subscription": { - "product_handle": "gold-product", - "coupon_code": "1DOLLAR", - "components": [ - { - "component_id": 462149, - "price_point_id": 200543, - "allocated_quantity": 14 - }, - { - "component_id": 426665, - "unit_balance": 20 - }, - { - "component_id": 426670, - "allocated_quantity": 1 - } - ] - } - } - }, - "With Custom Taxes": { - "value": { - "subscription": { - "product_handle": "paid-annual-seats", - "customer_attributes": { - "address": "870 Massachusetts Ave", - "address_2": null, - "city": "Boston", - "state": "MA", - "zip": "02118", - "country": "US" - } - } - } - }, - "With Avalara Taxes": { - "value": { - "subscription": { - "product_handle": "paid-annual-seats", - "credit_card_attributes": { - "billing_address": "870 Massachusetts Ave", - "billing_address_2": null, - "billing_city": "Boston", - "billing_state": "MA", - "billing_zip": "02118", - "billing_country": "US" - } - } - } - }, - "With Custom Pricing": { - "value": { - "subscription": { - "product_id": 1234, - "custom_price": { - "price_in_cents": 9900, - "interval": 1, - "interval_unit": "month" - }, - "components": [ - { - "component_id": 20, - "allocated_quantity": 10, - "custom_price": { - "pricing_scheme": "stairstep", - "prices": [ - { - "unit_price": 5, - "starting_quantity": 1, - "ending_quantity": 15 - }, - { - "unit_price": 2, - "starting_quantity": 16 - } - ] - } - }, - { - "component_id": 10, - "enabled": true, - "custom_price": { - "prices": [ - { - "unit_price": 1, - "starting_quantity": 1 - } - ] - } - } - ] - } - } - } - } - } - } - } - } - }, - "/chargify_js_keys.json": { - "get": { - "summary": "List Chargify.js Public Keys", - "tags": [ - "Sites" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Public-Keys-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "chargify_js_keys": [ - { - "public_key": "chjs_ftrxt7c4fv6f74wchjs_5zyn7gnwv", - "requires_security_token": false, - "created_at": "2021-01-01T05:00:00-04:00" - } - ], - "meta": { - "total_count": 1, - "current_page": 1, - "total_pages": 1, - "per_page": 10 - } - } - } - } - } - } - } - }, - "operationId": "listChargifyJsPublicKeys", - "description": "This endpoint returns public keys used for Chargify.js.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - } - ] - } - }, - "/subscription_groups/{uid}/proforma_invoices.json": { - "parameters": [ - { - "$ref": "../components/parameters/group-uid-path.yaml" - } - ], - "post": { - "summary": "Create Consolidated Proforma Invoices", - "tags": [ - "Proforma Invoices" - ], - "responses": { - "201": { - "description": "Created" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Consolidated proforma invoice generation already in progress" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createConsolidatedProformaInvoice", - "description": "This endpoint will trigger the creation of a consolidated proforma invoice asynchronously. It will return a 201 with no message, or a 422 with any errors. To find and view the new consolidated proforma invoice, you may poll the subscription group listing for proforma invoices; only one consolidated proforma invoice may be created per group at a time.\n\nIf the information becomes outdated, simply void the old consolidated proforma invoice and generate a new one.\n\n## Restrictions\n\nProforma invoices are only available on Relationship Invoicing sites. To create a proforma invoice, the subscription must not be prepaid, and must be in a live state." - }, - "get": { - "summary": "List Subscription Group Proforma Invoices", - "tags": [ - "Proforma Invoices" - ], - "operationId": "listSubscriptionGroupProformaInvoices", - "parameters": [ - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "line_items", - "description": "Include line items data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "discounts", - "description": "Include discounts data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "taxes", - "description": "Include taxes data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "credits", - "description": "Include credits data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "payments", - "description": "Include payments data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "custom_fields", - "description": "Include custom fields data" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Proforma-Invoices-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "collectParameters": true, - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "description": "Only proforma invoices with a `consolidation_level` of parent are returned.\n\nBy default, proforma invoices returned on the index will only include totals, not detailed breakdowns for `line_items`, `discounts`, `taxes`, `credits`, `payments`, `custom_fields`. To include breakdowns, pass the specific field as a key in the query with a value set to true.\n" - } - }, - "/proforma_invoices/{proforma_invoice_uid}.json": { - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "proforma_invoice_uid", - "in": "path", - "required": true, - "description": "The uid of the proforma invoice" - } - ], - "get": { - "summary": "Read Proforma Invoice", - "tags": [ - "Proforma Invoices" - ], - "operationId": "readProformaInvoice", - "description": "Use this endpoint to read the details of an existing proforma invoice.\n\n## Restrictions\n\nProforma invoices are only available on Relationship Invoicing sites.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Proforma-Invoice.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - } - } - }, - "/subscriptions/{subscription_id}/add_coupon.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Apply Coupons to Subscription", - "tags": [ - "Subscriptions" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": { - "id": 21607180, - "state": "active", - "trial_started_at": null, - "trial_ended_at": null, - "activated_at": "2018-04-20T14:20:57-05:00", - "created_at": "2018-04-20T14:20:57-05:00", - "updated_at": "2018-05-11T13:53:44-05:00", - "expires_at": null, - "balance_in_cents": 49000, - "current_period_ends_at": "2018-05-12T11:33:03-05:00", - "next_assessment_at": "2018-05-12T11:33:03-05:00", - "canceled_at": null, - "cancellation_message": null, - "next_product_id": null, - "cancel_at_end_of_period": false, - "payment_collection_method": "remittance", - "snap_day": null, - "cancellation_method": null, - "current_period_started_at": "2018-05-11T11:33:03-05:00", - "previous_state": "active", - "signup_payment_id": 237154761, - "signup_revenue": "0.00", - "delayed_cancel_at": null, - "coupon_code": "COUPONA", - "total_revenue_in_cents": 52762, - "product_price_in_cents": 100000, - "product_version_number": 2, - "payment_type": "credit_card", - "referral_code": "x45nc8", - "coupon_use_count": 0, - "coupon_uses_allowed": 1, - "reason_code": null, - "automatically_resume_at": null, - "coupon_codes": [ - "COUPONA", - "COUPONB" - ], - "customer": { - "id": 21259051, - "first_name": "K", - "last_name": "C", - "organization": "", - "email": "example@chargify.com", - "created_at": "2018-04-20T14:20:57-05:00", - "updated_at": "2018-04-23T15:29:28-05:00", - "reference": null, - "address": "", - "address_2": "", - "city": "", - "state": "", - "zip": "", - "country": "", - "phone": "", - "portal_invite_last_sent_at": "2018-04-20T14:20:59-05:00", - "portal_invite_last_accepted_at": null, - "verified": false, - "portal_customer_created_at": "2018-04-20T14:20:59-05:00", - "cc_emails": "", - "tax_exempt": false - }, - "product": { - "id": 4581816, - "name": "Basic", - "handle": "basic", - "description": "", - "accounting_code": "", - "request_credit_card": true, - "expiration_interval": null, - "expiration_interval_unit": "never", - "created_at": "2017-11-02T15:00:11-05:00", - "updated_at": "2018-04-10T09:02:59-05:00", - "price_in_cents": 100000, - "interval": 1, - "interval_unit": "month", - "initial_charge_in_cents": 100000, - "trial_price_in_cents": 1000, - "trial_interval": 10, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": true, - "return_params": "", - "taxable": false, - "update_return_url": "", - "tax_code": "", - "initial_charge_after_trial": false, - "version_number": 2, - "update_return_params": "", - "product_family": { - "id": 1025627, - "name": "My Product Family", - "description": "", - "handle": "acme-products", - "accounting_code": null - }, - "public_signup_pages": [ - { - "id": 333589, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargifypay.com/subscribe/hbwtd98j3hk2/basic" - }, - { - "id": 335926, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargifypay.com/subscribe/g366zy67c7rm/basic" - }, - { - "id": 345555, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargifypay.com/subscribe/txqyyqk7d8rz/basic" - }, - { - "id": 345556, - "return_url": "", - "return_params": "", - "url": "https://general-goods.chargifypay.com/subscribe/2zss3qpf4249/basic" - } - ] - }, - "credit_card": { - "id": 14839830, - "first_name": "John", - "last_name": "Doe", - "masked_card_number": "XXXX-XXXX-XXXX-1", - "card_type": "bogus", - "expiration_month": 1, - "expiration_year": 2028, - "customer_id": 21259051, - "current_vault": "bogus", - "vault_token": "1", - "billing_address": null, - "billing_city": null, - "billing_state": null, - "billing_zip": "99999", - "billing_country": null, - "customer_vault_token": null, - "billing_address_2": null, - "payment_type": "credit_card" - } - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Subscription-Add-Coupon-Error.yaml" - }, - "examples": { - "Example-1": { - "value": { - "coupon_codes": [ - "Coupon Codes: 'COUPONA' - That coupon is not stackable", - "Coupon Codes: 'COUPONB' - That coupon is not stackable" - ], - "subscription": [ - "Coupon is invalid." - ] - } - }, - "Example-2": { - "value": { - "coupon_code": [ - "Coupon Codes: 'COUPONA' - Coupon code could not be found." - ], - "subscription": [ - "Coupon is invalid." - ] - } - }, - "Example-3": { - "value": { - "codes": [ - "Coupon Codes: Subscription already has at least one non-stackable coupon." - ], - "subscription": [ - "Coupon is invalid." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "applyCouponsToSubscription", - "description": "An existing subscription can accommodate multiple discounts/coupon codes. This is only applicable if each coupon is stackable. For more information on stackable coupons, we recommend reviewing our [coupon documentation.](https://chargify.zendesk.com/hc/en-us/articles/4407755909531#stackable-coupons)\n\n## Query Parameters vs Request Body Parameters\n\nPassing in a coupon code as a query parameter will add the code to the subscription, completely replacing all existing coupon codes on the subscription.\n\nFor this reason, using this query parameter on this endpoint has been deprecated in favor of using the request body parameters as described below. When passing in request body parameters, the list of coupon codes will simply be added to any existing list of codes on the subscription.", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "code", - "description": "A code for the coupon that would be applied to a subscription", - "deprecated": true - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Add-Coupons-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "codes": [ - "COUPON_1", - "COUPON_2" - ] - } - } - } - } - } - } - } - }, - "/subscriptions/{subscription_id}/remove_coupon.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "delete": { - "summary": "Remove Coupon from Subscription", - "tags": [ - "Subscriptions" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "string" - }, - "examples": { - "Example": { - "value": "Coupon successfully removed" - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Subscription-Remove-Coupon-Errors.yaml" - }, - "examples": { - "Example": { - "value": { - "subscription": [ - "There's no coupon applied to this subscription" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "removeCouponFromSubscription", - "description": "Use this endpoint to remove a coupon from an existing subscription.\n\nFor more information on the expected behaviour of removing a coupon from a subscription, please see our documentation [here.](https://chargify.zendesk.com/hc/en-us/articles/4407896488987#removing-a-coupon)", - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "coupon_code", - "description": "The coupon code" - } - ] - } - }, - "/subscriptions/{subscription_id}/proforma_invoices.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Create Proforma Invoice", - "tags": [ - "Proforma Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Proforma-Invoice.yaml" - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "this subscription is not eligible to create proforma invoices" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createProformaInvoice", - "description": "This endpoint will create a proforma invoice and return it as a response. If the information becomes outdated, simply void the old proforma invoice and generate a new one.\n\nIf you would like to preview the next billing amounts without generating a full proforma invoice, please use the renewal preview endpoint.\n\n## Restrictions\n\nProforma invoices are only available on Relationship Invoicing sites. To create a proforma invoice, the subscription must not be in a group, must not be prepaid, and must be in a live state." - }, - "get": { - "summary": "List Subscription Proforma Invoices", - "tags": [ - "Proforma Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Proforma-Invoices-Response.yaml" - } - } - } - } - }, - "operationId": "listProformaInvoices", - "description": "By default, proforma invoices returned on the index will only include totals, not detailed breakdowns for `line_items`, `discounts`, `taxes`, `credits`, `payments`, or `custom_fields`. To include breakdowns, pass the specific field as a key in the query with a value set to `true`.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_date", - "description": "The beginning date range for the invoice's Due Date, in the YYYY-MM-DD format." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_date", - "description": "The ending date range for the invoice's Due Date, in the YYYY-MM-DD format." - }, - { - "schema": { - "$ref": "../components/schemas/Proforma-Invoice-Status.yaml" - }, - "in": "query", - "name": "status", - "description": "The current status of the invoice. Allowed Values: draft, open, paid, pending, voided" - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "string", - "enum": [ - "asc", - "desc" - ], - "default": "desc" - }, - "in": "query", - "name": "direction", - "description": "The sort direction of the returned invoices." - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "line_items", - "description": "Include line items data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "discounts", - "description": "Include discounts data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "taxes", - "description": "Include taxes data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "credits", - "description": "Include credits data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "payments", - "description": "Include payments data" - }, - { - "schema": { - "type": "boolean", - "default": false - }, - "in": "query", - "name": "custom_fields", - "description": "Include custom fields data" - } - ] - } - }, - "/proforma_invoices/{proforma_invoice_uid}/void.json": { - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "proforma_invoice_uid", - "in": "path", - "required": true, - "description": "The uid of the proforma invoice" - } - ], - "post": { - "summary": "Void Proforma Invoice", - "tags": [ - "Proforma Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Proforma-Invoice.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "You must provide a reason for voiding the proforma invoice.", - "Only draft proforma invoices may be voided." - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "voidProformaInvoice", - "description": "This endpoint will void a proforma invoice that has the status \"draft\".\n\n## Restrictions\n\nProforma invoices are only available on Relationship Invoicing sites.\n\nOnly proforma invoices that have the appropriate status may be reopened. If the invoice identified by {uid} does not have the appropriate status, the response will have HTTP status code 422 and an error message.\n\nA reason for the void operation is required to be included in the request body. If one is not provided, the response will have HTTP status code 422 and an error message.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Void-Invoice-Request.yaml" - } - } - }, - "description": "" - } - } - }, - "/subscriptions/{subscription_id}/proforma_invoices/preview.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Preview Proforma Invoice", - "tags": [ - "Proforma Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Proforma-Invoice.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "example-1": { - "value": { - "errors": [ - "this subscription is not eligible to create proforma invoices" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "previewProformaInvoice", - "description": "Return a preview of the data that will be included on a given subscription's proforma invoice if one were to be generated. It will have similar line items and totals as a renewal preview, but the response will be presented in the format of a proforma invoice. Consequently it will include additional information such as the name and addresses that will appear on the proforma invoice.\n\nThe preview endpoint is subject to all the same conditions as the proforma invoice endpoint. For example, previews are only available on the Relationship Invoicing architecture, and previews cannot be made for end-of-life subscriptions.\n\nIf all the data returned in the preview is as expected, you may then create a static proforma invoice and send it to your customer. The data within a preview will not be saved and will not be accessible after the call is made.\n\nAlternatively, if you have some proforma invoices already, you may make a preview call to determine whether any billing information for the subscription's upcoming renewal has changed." - } - }, - "/invoices/{uid}/deliveries.json": { - "parameters": [ - { - "$ref": "../components/parameters/invoice-uid-path.yaml" - } - ], - "post": { - "summary": "Send Invoice", - "tags": [ - "Invoices" - ], - "responses": { - "204": { - "description": "No Content" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "cc_recipient_emails: must be a valid email address" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "sendInvoice", - "description": "This endpoint allows for invoices to be programmatically delivered via email. This endpoint supports the delivery of both ad-hoc and automatically generated invoices. Additionally, this endpoint supports email delivery to direct recipients, carbon-copy (cc) recipients, and blind carbon-copy (bcc) recipients.\n\nPlease note that if no recipient email addresses are specified in the request, then the subscription's default email configuration will be used. For example, if `recipient_emails` is left blank, then the invoice will be delivered to the subscription's customer email address.\n\nOn success, a 204 no-content response will be returned. Please note that this does not indicate that email(s) have been delivered, but instead indicates that emails have been successfully queued for delivery. If _any_ invalid or malformed email address is found in the request body, the entire request will be rejected and a 422 response will be returned.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Send-Invoice-Request.yaml" - }, - "examples": { - "Example": { - "value": { - "recipient_emails": [ - "user0@example.com" - ], - "cc_recipient_emails": [ - "user1@example.com" - ], - "bcc_recipient_emails": [ - "user2@example.com" - ] - } - } - } - } - } - } - } - }, - "/invoices/{uid}/customer_information/preview.json": { - "parameters": [ - { - "$ref": "../components/parameters/invoice-uid-path.yaml" - } - ], - "post": { - "summary": "Preview Customer Information Changes", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Customer-Changes-Preview-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "changes": { - "payer": { - "before": { - "last_name": "Beatty" - }, - "after": { - "last_name": "Doe" - } - }, - "shipping_address": { - "before": { - "line2": "Suite 703" - }, - "after": { - "line2": "Suite 702" - } - }, - "billing_address": { - "before": { - "line2": "Suite 703" - }, - "after": { - "line2": "Suite 702" - } - }, - "custom_fields": { - "before": [ - { - "owner_id": 1002, - "owner_type": "Customer", - "name": "Color", - "value": "blue", - "metadatum_id": 20 - } - ], - "after": [ - { - "owner_id": 1002, - "owner_type": "Customer", - "name": "Color", - "value": "green", - "metadatum_id": 20 - } - ] - } - } - } - } - } - } - } - }, - "404": { - "description": "Not Found", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Invoice not found" - ] - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Invoice must have an open status" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "previewCustomerInformationChanges", - "description": "Customer information may change after an invoice is issued which may lead to a mismatch between customer information that are present on an open invoice and actual customer information. This endpoint allows to preview these differences, if any.\n\nThe endpoint doesn't accept a request body. Customer information differences are calculated on the application side." - } - }, - "/invoices/{uid}/customer_information.json": { - "parameters": [ - { - "$ref": "../components/parameters/invoice-uid-path.yaml" - } - ], - "put": { - "summary": "Update Customer Information", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Invoice.yaml" - }, - "examples": { - "Example": { - "value": { - "uid": "elit Ut", - "site_id": 46283786, - "customer_id": -62349460, - "subscription_id": 12801726, - "number": "dolore et ut", - "sequence_number": -84210096, - "issue_date": "2017-01-01", - "due_date": "2017-01-30", - "paid_date": "2017-01-28", - "status": "open", - "collection_method": "automatic", - "payment_instructions": "enim officia", - "currency": "dolore", - "consolidation_level": "none", - "product_name": "occaecat veniam culpa", - "product_family_name": "qui commodo ea dolore cillum", - "seller": { - "name": "co", - "phone": "ullamco in officia" - }, - "customer": { - "chargify_id": -55826334, - "first_name": "deserunt", - "last_name": "velit dolore", - "email": "aliquip sed velit Lorem" - }, - "memo": "ea cupidatat deserunt", - "billing_address": { - "street": "qui commodo cupidatat sunt", - "line2": "ut officia enim", - "city": "velit minim dolore sint nulla", - "state": "velit", - "zip": "ullamco", - "country": "irure est laborum deserun" - }, - "shipping_address": { - "street": "do fugiat dolore deserunt officia", - "line2": "ipsum cillum", - "city": "aliqua laboris incididunt ut", - "state": "et fugiat sit", - "zip": "dolore do", - "country": "Excepteur consequat cillum" - }, - "subtotal_amount": "dolore mollit", - "discount_amount": "aute", - "tax_amount": "eu aliqua est velit ea", - "total_amount": "ut non", - "credit_amount": "sit", - "refund_amount": "et eiusmod qui sed", - "paid_amount": "amet nulla s", - "due_amount": "non esse ullamco", - "line_items": [ - { - "description": "qui", - "price_point_id": 123, - "tax_amount": "occaecat deserunt veniam", - "subtotal_amount": "commodo consequat tempor et Duis" - }, - { - "uid": "", - "subtotal_amount": "ven" - }, - { - "price_point_id": 94750853, - "product_id": 79058036, - "tax_amount": "1.0", - "subtotal_amount": "128.5" - }, - { - "unit_price": "eiusmod consequat ut nostrud", - "tax_amount": "quis nulla proident" - }, - { - "period_range_end": "2022-02-02", - "product_id": 57352537, - "description": "minim in dolore Ut Excepteur", - "uid": "sit qui in ullamco anim" - } - ], - "discounts": [ - { - "title": "nostrud" - } - ], - "taxes": [ - { - "source_type": "Tax", - "line_item_breakouts": [ - { - "uid": "in ipsum", - "tax_amount": "velit", - "taxable_amount": "quis sint" - }, - { - "uid": "co" - } - ] - }, - { - "uid": "enim irure in", - "title": "incididunt est mollit irure" - } - ], - "credits": [ - { - "uid": "exercitation eiusmod", - "transaction_time": "2024-01-23T13:51:27Z", - "credit_note_number": "qui fugiat labore laborum", - "credit_note_uid": "ipsum sunt" - }, - { - "memo": "dolor" - } - ], - "refunds": [ - { - "memo": "deserunt elit" - }, - { - "original_amount": "Duis nulla" - } - ], - "payments": [ - { - "prepayment": false, - "memo": "enim Excepteur Lorem magna sit" - }, - { - "transaction_time": "2024-01-23T13:51:27Z", - "prepayment": false, - "payment_method": { - "details": "labore ut et", - "kind": "dolor qui", - "memo": "ea commodo", - "type": "fugiat veniam", - "card_brand": "consequat", - "card_expiration": "aliqua a", - "last_four": "ut in consectetur sed", - "masked_card_number": "minim ea ullamco nostrud tempor" - } - }, - { - "prepayment": true, - "transaction_id": 67527234 - }, - { - "original_amount": "c", - "memo": "dolore fugiat labore" - } - ], - "custom_fields": [ - { - "name": "CustomerStatus", - "value": "Gold", - "owner_type": "Customer", - "owner_id": 18482224, - "metadatum_id": 13924 - }, - { - "name": "SubscriptionTag", - "value": "Special Subscriber", - "owner_type": "Subscription", - "owner_id": 21344, - "metadatum_id": 139245 - } - ], - "public_url": "dolo", - "previous_balance_data": { - "captured_at": "2024-01-09T11:22:23-05:00", - "invoices": [ - { - "number": "veniam dolore labore ipsum cupidatat", - "uid": "tempor", - "outstanding_amount": "Excepteur nostrud irur" - }, - { - "outstanding_amount": "id" - } - ] - } - } - } - } - } - } - }, - "404": { - "description": "Not Found", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Invoice not found" - ] - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": [ - "Invoice must have an open status" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updateCustomerInformation", - "description": "This endpoint updates customer information on an open invoice and returns the updated invoice. If you would like to preview changes that will be applied, use the `/invoices/{uid}/customer_information/preview.json` endpoint before.\n\nThe endpoint doesn't accept a request body. Customer information differences are calculated on the application side." - } - }, - "/one_time_tokens/{chargify_token}.json": { - "get": { - "summary": "Read one time token details", - "tags": [ - "Payment Profiles" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Get-One-Time-Token-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "example-1": { - "value": { - "errors": [ - "Chargify token not found" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "readOneTimeToken", - "x-internal": false, - "description": "One Time Tokens aka Chargify Tokens house the credit card or ACH (Authorize.Net or Stripe only) data for a customer.\n\nYou can use One Time Tokens while creating a subscription or payment profile instead of passing all bank account or credit card data directly to a given API endpoint.\n\nTo obtain a One Time Token you have to use [chargify.js](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0NjAzNDI0-overview)." - }, - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "chargify_token", - "in": "path", - "required": true, - "description": "Chargify Token" - } - ] - }, - "/subscriptions_components.json": { - "get": { - "summary": "List Subscription Components for Site", - "tags": [ - "Subscription Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Subscription-Components-Response.yaml" - } - } - } - } - }, - "operationId": "listSubscriptionComponentsForSite", - "description": "This request will list components applied to each subscription.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "$ref": "../components/schemas/List-Subscription-Components-Sort.yaml" - }, - "in": "query", - "name": "sort", - "description": "The attribute by which to sort. Use in query: `sort=updated_at`." - }, - { - "$ref": "../components/parameters/sort-direction.yaml" - }, - { - "schema": { - "$ref": "../components/schemas/Subscription-List-Date-Field.yaml" - }, - "in": "query", - "name": "date_field", - "description": "The type of filter you'd like to apply to your search. Use in query: `date_field=updated_at`." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_date", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. Use in query `start_date=2011-12-15`." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "start_datetime", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of start_date. Use in query `start_datetime=2022-07-01 09:00:05`." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "end_date", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. Use in query `end_date=2011-12-16`." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of end_date. Use in query `end_datetime=2022-07-01 09:00:05`.", - "name": "end_datetime" - }, - { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [ - 1, - 2, - 3 - ], - "maxLength": 200, - "minLength": 1, - "minItems": 1, - "maxItems": 200 - }, - "style": "form", - "explode": false, - "in": "query", - "name": "subscription_ids", - "description": "Allows fetching components allocation with matching subscription id based on provided ids. Use in query `subscription_ids=1,2,3`." - }, - { - "schema": { - "$ref": "../components/schemas/Include-Not-Null.yaml" - }, - "in": "query", - "name": "price_point_ids", - "description": "Allows fetching components allocation only if price point id is present. Use in query `price_point_ids=not_null`." - }, - { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [ - 1, - 2, - 3 - ] - }, - "in": "query", - "name": "product_family_ids", - "description": "Allows fetching components allocation with matching product family id based on provided ids. Use in query `product_family_ids=1,2,3`.", - "style": "form", - "explode": false - }, - { - "schema": { - "$ref": "../components/schemas/List-Subscription-Components-Include.yaml" - }, - "in": "query", - "name": "include", - "description": "Allows including additional data in the response. Use in query `include=subscription`." - }, - { - "schema": { - "type": "boolean", - "example": true - }, - "in": "query", - "name": "filter[use_site_exchange_rate]", - "description": "Allows fetching components allocation with matching use_site_exchange_rate based on provided value. Use in query `filter[use_site_exchange_rate]=true`." - }, - { - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "EUR", - "USD" - ] - }, - "in": "query", - "name": "filter[currencies]", - "description": "Allows fetching components allocation with matching currency based on provided values. Use in query `filter[currencies]=USD,EUR`.", - "style": "form", - "explode": false - }, - { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Subscription-State-Filter.yaml" - }, - "example": [ - "active", - "canceled" - ] - }, - "in": "query", - "name": "filter[subscription][states]", - "style": "form", - "explode": false, - "description": "Allows fetching components allocations that belong to the subscription with matching states based on provided values. To use this filter you also have to include the following param in the request `include=subscription`. Use in query `filter[subscription][states]=active,canceled&include=subscription`." - }, - { - "schema": { - "$ref": "../components/schemas/Subscription-List-Date-Field.yaml" - }, - "in": "query", - "name": "filter[subscription][date_field]", - "description": "The type of filter you'd like to apply to your search. To use this filter you also have to include the following param in the request `include=subscription`." - }, - { - "schema": { - "type": "string", - "format": "date" - }, - "in": "query", - "name": "filter[subscription][start_date]", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns components that belong to the subscription with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. To use this filter you also have to include the following param in the request `include=subscription`." - }, - { - "schema": { - "type": "string", - "format": "date-time" - }, - "in": "query", - "name": "filter[subscription][start_datetime]", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components that belong to the subscription with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of start_date. To use this filter you also have to include the following param in the request `include=subscription`." - }, - { - "schema": { - "type": "string", - "format": "date" - }, - "in": "query", - "name": "filter[subscription][end_date]", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns components that belong to the subscription with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. To use this filter you also have to include the following param in the request `include=subscription`." - }, - { - "schema": { - "type": "string", - "format": "date-time" - }, - "in": "query", - "name": "filter[subscription][end_datetime]", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components that belong to the subscription with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of end_date. To use this filter you also have to include the following param in the request `include=subscription`." - } - ] - } - }, - "/components/{component_id}/price_points/{price_point_id}/segments.json": { - "post": { - "summary": "Create Single Segment", - "tags": [ - "Events-Based Billing: Segments" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Segment-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Event-Based-Billing-Segment-Errors.yaml" - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createSegment", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Segment-Request.yaml" - }, - "examples": { - "Create a Single Segment (related Metric has 2 segmented properties)": { - "value": { - "segment": { - "segment_property_1_value": "France", - "segment_property_2_value": "Spain", - "pricing_scheme": "volume", - "prices": [ - { - "starting_quantity": 1, - "ending_quantity": 10000, - "unit_price": 0.19 - }, - { - "starting_quantity": 10001, - "unit_price": 0.09 - } - ] - } - } - } - } - } - } - }, - "description": "This endpoint creates a new Segment for a Component with segmented Metric. It allows you to specify properties to bill upon and prices for each Segment. You can only pass as many \"property_values\" as the related Metric has segmenting properties defined.\n\nYou may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax." - }, - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "ID or Handle for the Component" - }, - { - "schema": { - "type": "string" - }, - "name": "price_point_id", - "in": "path", - "required": true, - "description": "ID or Handle for the Price Point belonging to the Component" - } - ], - "get": { - "summary": "List Segments for a Price Point", - "operationId": "listSegmentsForPricePoint", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Segments-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Event-Based-Billing-List-Segments-Errors.yaml" - } - } - } - } - }, - "description": "This endpoint allows you to fetch Segments created for a given Price Point. They will be returned in the order of creation.\n\nYou can pass `page` and `per_page` parameters in order to access all of the segments. By default it will return `30` records. You can set `per_page` to `200` at most.\n\nYou may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax.", - "x-operation-settings": { - "collectParameters": true, - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "parameters": [ - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page-default-30.yaml" - }, - { - "schema": { - "type": "string", - "example": "EU" - }, - "in": "query", - "name": "filter[segment_property_1_value]", - "description": "The value passed here would be used to filter segments. Pass a value related to `segment_property_1` on attached Metric. If empty string is passed, this filter would be rejected. Use in query `filter[segment_property_1_value]=EU`." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "filter[segment_property_2_value]", - "description": "The value passed here would be used to filter segments. Pass a value related to `segment_property_2` on attached Metric. If empty string is passed, this filter would be rejected." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "filter[segment_property_3_value]", - "description": "The value passed here would be used to filter segments. Pass a value related to `segment_property_3` on attached Metric. If empty string is passed, this filter would be rejected." - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "filter[segment_property_4_value]", - "description": "The value passed here would be used to filter segments. Pass a value related to `segment_property_4` on attached Metric. If empty string is passed, this filter would be rejected." - } - ], - "tags": [ - "Events-Based Billing: Segments" - ] - } - }, - "/components/{component_id}/price_points/{price_point_id}/segments/{id}.json": { - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "ID or Handle of the Component" - }, - { - "schema": { - "type": "string" - }, - "name": "price_point_id", - "in": "path", - "required": true, - "description": "ID or Handle of the Price Point belonging to the Component" - }, - { - "schema": { - "type": "number" - }, - "name": "id", - "in": "path", - "required": true, - "description": "The ID of the Segment" - } - ], - "put": { - "summary": "Update Single Segment", - "tags": [ - "Events-Based Billing: Segments" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Segment-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Event-Based-Billing-Segment-Errors.yaml" - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "updateSegment", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Update-Segment-Request.yaml" - } - } - } - }, - "description": "This endpoint updates a single Segment for a Component with a segmented Metric. It allows you to update the pricing for the segment.\n\nYou may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax." - }, - "delete": { - "summary": "Delete Single Segment", - "operationId": "deleteSegment", - "responses": { - "204": { - "description": "No Content" - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "description": "This endpoint allows you to delete a Segment with specified ID.\n\nYou may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax.", - "tags": [ - "Events-Based Billing: Segments" - ] - } - }, - "/components/{component_id}/price_points/{price_point_id}/segments/bulk.json": { - "parameters": [ - { - "schema": { - "type": "string" - }, - "name": "component_id", - "in": "path", - "required": true, - "description": "ID or Handle for the Component" - }, - { - "schema": { - "type": "string" - }, - "name": "price_point_id", - "in": "path", - "required": true, - "description": "ID or Handle for the Price Point belonging to the Component" - } - ], - "post": { - "summary": "Bulk Create Segments", - "tags": [ - "Events-Based Billing: Segments" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Segments-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Event-Based-Billing-Segment.yaml" - }, - "examples": { - "Error response when Pricing Scheme is missing": { - "value": { - "errors": { - "segments": { - "1": { - "pricing_scheme": [ - "Pricing scheme: cannot be blank" - ] - } - } - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "bulkCreateSegments", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Bulk-Create-Segments.yaml" - } - } - } - }, - "description": "This endpoint allows you to create multiple segments in one request. The array of segments can contain up to `2000` records.\n\nIf any of the records contain an error the whole request would fail and none of the requested segments get created. The error response contains a message for only the one segment that failed validation, with the corresponding index in the array.\n\nYou may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax." - }, - "put": { - "summary": "Bulk Update Segments", - "tags": [ - "Events-Based Billing: Segments" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Segments-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Event-Based-Billing-Segment.yaml" - }, - "examples": { - "Error response when Pricing Scheme is missing": { - "value": { - "errors": { - "segments": { - "1": { - "pricing_scheme": [ - "Pricing scheme: cannot be blank" - ] - } - } - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "bulkUpdateSegments", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Bulk-Update-Segments.yaml" - } - } - } - }, - "description": "This endpoint allows you to update multiple segments in one request. The array of segments can contain up to `1000` records.\n\nIf any of the records contain an error the whole request would fail and none of the requested segments get updated. The error response contains a message for only the one segment that failed validation, with the corresponding index in the array.\n\nYou may specify component and/or price point by using either the numeric ID or the `handle:gold` syntax." - } - }, - "/subscriptions/{subscription_id}/advance_invoice/issue.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Issue advance invoice", - "tags": [ - "Advance Invoice" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Invoice.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Nothing due": { - "value": { - "errors": [ - "Cannot generate an invoice in advance when nothing is due" - ] - } - }, - "Already exists": { - "value": { - "errors": [ - "Advance invoice already exists" - ] - } - }, - "Grouped": { - "value": { - "errors": [ - "Cannot generate an invoice in advance for subscription in the group" - ] - } - }, - "End of life": { - "value": { - "errors": [ - "Cannot generate an invoice in advance for inactive subscription" - ] - } - }, - "Calendar billing": { - "value": { - "errors": [ - "Cannot generate an invoice in advance for a calendar billing subscription" - ] - } - }, - "Prepaid subscription": { - "value": { - "errors": [ - "Cannot generate an invoice in advance for a prepaid subscription" - ] - } - }, - "Close to renewal": { - "value": { - "errors": [ - "Cannot generate an invoice in advance within an hour of renewal" - ] - } - }, - "Custom exchange": { - "value": { - "errors": [ - "Cannot generate an invoice in advance for a subscription using the site level exchange rate" - ] - } - }, - "Prepaid components": { - "value": { - "errors": [ - "Cannot generate an invoice in advance when a subscription uses prepaid components" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "issueAdvanceInvoice", - "description": "Generate an invoice in advance for a subscription's next renewal date. [Please see our docs](reference/Chargify-API.v1.yaml/components/schemas/Invoice) for more information on advance invoices, including eligibility on generating one; for the most part, they function like any other invoice, except they are issued early and have special behavior upon being voided.\nA subscription may only have one advance invoice per billing period. Attempting to issue an advance invoice when one already exists will return an error.\nThat said, regeneration of the invoice may be forced with the params `force: true`, which will void an advance invoice if one exists and generate a new one. If no advance invoice exists, a new one will be generated.\nWe recommend using either the create or preview endpoints for proforma invoices to preview this advance invoice before using this endpoint to generate it.\n", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Issue-Advance-Invoice-Request.yaml" - }, - "examples": { - "Force generation": { - "value": { - "force": true - } - } - } - } - } - } - } - }, - "/subscriptions/{subscription_id}/advance_invoice.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "get": { - "summary": "Read advance invoice", - "tags": [ - "Advance Invoice" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Invoice.yaml" - }, - "examples": {} - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "readAdvanceInvoice", - "description": "Once an advance invoice has been generated for a subscription's upcoming renewal, it can be viewed through this endpoint. There can only be one advance invoice per subscription per billing cycle." - } - }, - "/subscriptions/{subscription_id}/advance_invoice/void.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Void advance invoice", - "tags": [ - "Advance Invoice" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Invoice.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - }, - "operationId": "voidAdvanceInvoice", - "description": "Void a subscription's existing advance invoice. Once voided, it can later be regenerated if desired.\nA `reason` is required in order to void, and the invoice must have an open status. Voiding will cause any prepayments and credits that were applied to the invoice to be returned to the subscription. For a full overview of the impact of voiding, please [see our help docs](reference/Chargify-API.v1.yaml/components/schemas/Invoice).", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Void-Invoice-Request.yaml" - } - } - } - } - } - }, - "/subscriptions_mrr.json": { - "get": { - "summary": "List MRR per subscription", - "tags": [ - "Insights" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Mrr-Response.yaml" - } - } - } - }, - "400": { - "description": "Bad Request", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Subscriptions-MRR-Error-Response.yaml" - }, - "examples": { - "example-1": { - "value": { - "errors": { - "attribute": [ - "supplied value is invalid, expected ISO 8601 format" - ] - } - } - } - } - } - } - } - }, - "operationId": "listMrrPerSubscription", - "deprecated": true, - "description": "This endpoint returns your site's current MRR, including plan and usage breakouts split per subscription.", - "x-operation-settings": { - "ErrorTemplates": { - "400": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - }, - "collectParameters": true - }, - "parameters": [ - { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [ - 1, - 2, - 3 - ], - "minLength": 1 - }, - "in": "query", - "name": "filter[subscription_ids]", - "description": "Submit ids in order to limit results. Use in query: `filter[subscription_ids]=1,2,3`.", - "style": "form", - "explode": false - }, - { - "schema": { - "type": "string", - "example": "at_time=2022-01-10T10:00:00-05:00" - }, - "in": "query", - "name": "at_time", - "description": "Submit a timestamp in ISO8601 format to request MRR for a historic time. Use in query: `at_time=2022-01-10T10:00:00-05:00`." - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "string", - "enum": [ - "asc", - "desc" - ], - "example": "desc" - }, - "in": "query", - "name": "direction", - "description": "Controls the order in which results are returned. Records are ordered by subscription_id in ascending order by default. Use in query `direction=desc`." - } - ] - } - }, - "/subscriptions/{subscription_id}/prepayments/{prepayment_id}/refunds.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - }, - { - "schema": { - "type": "integer", - "format": "int64" - }, - "name": "prepayment_id", - "in": "path", - "required": true, - "description": "id of prepayment" - } - ], - "post": { - "summary": "Refund Prepayment", - "tags": [ - "Subscription Invoice Account" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Prepayment-Response.yaml" - } - } - } - }, - "400": { - "description": "Bad Request", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Refund-Prepayment-Base-Errors-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found", - "content": { - "application/json": { - "schema": { - "type": "string" - } - } - } - }, - "422": { - "description": "Unprocessable Entity", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Refund-Prepayment-Error-Response.yaml" - }, - "examples": { - "Example-1": { - "value": { - "errors": { - "refund": "can't be blank" - } - } - }, - "Example-2": { - "value": { - "errors": { - "refund": { - "base": [ - "Memo: cannot be blank." - ] - } - } - } - }, - "Example-3": { - "value": { - "errors": { - "refund": { - "base": [ - "Amount: must be greater than 0." - ] - } - } - } - }, - "Example-4": { - "value": { - "errors": { - "refund": { - "amount_in_cents": [ - "Refund amount exceeds prepayment amount" - ] - } - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "400": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.", - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "refundPrepayment", - "description": "This endpoint will refund, completely or partially, a particular prepayment applied to a subscription. The `prepayment_id` will be the account transaction ID of the original payment. The prepayment must have some amount remaining in order to be refunded.\n\nThe amount may be passed either as a decimal, with `amount`, or an integer in cents, with `amount_in_cents`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Refund-Prepayment-Request.yaml" - } - } - } - } - } - }, - "/products.json": { - "get": { - "summary": "List Products", - "tags": [ - "Products" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Product-Response.yaml" - } - }, - "examples": { - "example-1": { - "value": [ - { - "product": { - "id": 0, - "name": "string", - "handle": "string", - "description": "string", - "accounting_code": "string", - "request_credit_card": true, - "expiration_interval": 0, - "expiration_interval_unit": "month", - "created_at": "2023-11-23T10:28:34-05:00", - "updated_at": "2023-11-23T10:28:34-05:00", - "price_in_cents": 0, - "interval": 0, - "interval_unit": "month", - "initial_charge_in_cents": 0, - "trial_price_in_cents": 0, - "trial_interval": 0, - "trial_interval_unit": "month", - "archived_at": null, - "require_credit_card": true, - "return_params": "string", - "taxable": true, - "update_return_url": "string", - "initial_charge_after_trial": true, - "version_number": 0, - "update_return_params": "string", - "product_family": { - "id": 0, - "name": "string", - "handle": "string", - "accounting_code": null, - "description": "string", - "created_at": "2021-05-05T16:00:21-04:00", - "updated_at": "2021-05-05T16:00:21-04:00" - }, - "public_signup_pages": [ - { - "id": 0, - "return_url": "string", - "return_params": "string", - "url": "string" - } - ], - "product_price_point_name": "string", - "request_billing_address": true, - "require_billing_address": true, - "require_shipping_address": true, - "use_site_exchange_rate": true, - "tax_code": "string", - "default_product_price_point_id": 0 - } - } - ] - } - } - } - } - } - }, - "operationId": "listProducts", - "description": "This method allows to retrieve a list of Products belonging to a Site.", - "x-operation-settings": { - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/basic-date-field.yaml" - }, - { - "schema": { - "type": "string", - "format": "date" - }, - "in": "query", - "name": "end_date", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns products with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string", - "format": "date-time" - }, - "in": "query", - "name": "end_datetime", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns products with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of end_date." - }, - { - "schema": { - "type": "string", - "format": "date" - }, - "in": "query", - "name": "start_date", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns products with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string", - "format": "date-time" - }, - "in": "query", - "name": "start_datetime", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns products with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of start_date." - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "boolean", - "example": true - }, - "in": "query", - "name": "include_archived", - "description": "Include archived products. Use in query: `include_archived=true`." - }, - { - "schema": { - "$ref": "../components/schemas/List-Products-Include.yaml" - }, - "in": "query", - "name": "include", - "description": "Allows including additional data in the response. Use in query `include=prepaid_product_price_point`." - }, - { - "schema": { - "$ref": "../components/schemas/Include-Not-Null.yaml" - }, - "in": "query", - "name": "filter[prepaid_product_price_point][product_price_point_id]", - "description": "Allows fetching products only if a prepaid product price point is present or not. To use this filter you also have to include the following param in the request `include=prepaid_product_price_point`. Use in query `filter[prepaid_product_price_point][product_price_point_id]=not_null`." - }, - { - "schema": { - "type": "boolean", - "example": true - }, - "in": "query", - "name": "filter[use_site_exchange_rate]", - "description": "Allows fetching products with matching use_site_exchange_rate based on provided value (refers to default price point). Use in query `filter[use_site_exchange_rate]=true`." - } - ] - } - }, - "/invoices/{uid}/issue.json": { - "parameters": [ - { - "$ref": "../components/parameters/invoice-uid-path.yaml" - } - ], - "post": { - "summary": "Issue Invoice", - "tags": [ - "Invoices" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Invoice.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "issueInvoice", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Issue-Invoice-Request.yaml" - } - } - }, - "description": "" - }, - "description": "This endpoint allows you to issue an invoice that is in \"pending\" status. For example, you can issue an invoice that was created when allocating new quantity on a component and using \"accrue charges\" option.\n\nYou cannot issue a pending child invoice that was created for a member subscription in a group.\n\nFor Remittance subscriptions, the invoice will go into \"open\" status and payment won't be attempted. The value for `on_failed_payment` would be rejected if sent. Any prepayments or service credits that exist on subscription will be automatically applied. Additionally, if setting is on, an email will be sent for issued invoice.\n\nFor Automatic subscriptions, prepayments and service credits will apply to the invoice and before payment is attempted. On successful payment, the invoice will go into \"paid\" status and email will be sent to the customer (if setting applies). When payment fails, the next event depends on the `on_failed_payment` value:\n- `leave_open_invoice` - prepayments and credits applied to invoice; invoice status set to \"open\"; email sent to the customer for the issued invoice (if setting applies); payment failure recorded in the invoice history. This is the default option.\n- `rollback_to_pending` - prepayments and credits not applied; invoice remains in \"pending\" status; no email sent to the customer; payment failure recorded in the invoice history.\n- `initiate_dunning` - prepayments and credits applied to the invoice; invoice status set to \"open\"; email sent to the customer for the issued invoice (if setting applies); payment failure recorded in the invoice history; subscription will most likely go into \"past_due\" or \"canceled\" state (depending upon net terms and dunning settings)." - } - }, - "/components_price_points.json": { - "get": { - "summary": "List All Components Price Points", - "tags": [ - "Components" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Components-Price-Points-Response.yaml" - }, - "examples": { - "example": { - "value": { - "price_points": [ - { - "id": 1, - "name": "Auto-created", - "type": "default", - "pricing_scheme": "per_unit", - "component_id": 2, - "handle": "auto-created", - "archived_at": null, - "created_at": "2021-02-21T11:05:57-05:00", - "updated_at": "2021-02-21T11:05:57-05:00", - "prices": [ - { - "id": 3, - "component_id": 2, - "starting_quantity": 0, - "ending_quantity": null, - "unit_price": "1.0", - "price_point_id": 1, - "formatted_unit_price": "$1.00", - "segment_id": null - } - ], - "tax_included": false - } - ] - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Invalid date format": { - "value": { - "errors": [ - "start_date supplied value is invalid, expected ISO 8601 format" - ] - } - } - } - } - } - } - }, - "operationId": "listAllComponentPricePoints", - "description": "This method allows to retrieve a list of Components Price Points belonging to a Site.", - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - }, - "collectParameters": true - }, - "parameters": [ - { - "schema": { - "$ref": "../components/schemas/Basic-Date-Field.yaml" - }, - "in": "query", - "name": "filter[date_field]", - "description": "The type of filter you would like to apply to your search. Use in query: `filter[date_field]=created_at`." - }, - { - "schema": { - "type": "string", - "format": "date" - }, - "in": "query", - "name": "filter[end_date]", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns price points with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string", - "format": "date-time", - "example": "2019-06-07T17:20:06Z" - }, - "in": "query", - "name": "filter[end_datetime]", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns price points with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date." - }, - { - "schema": { - "$ref": "../components/schemas/List-Components-Price-Points-Include.yaml" - }, - "in": "query", - "name": "include", - "description": "Allows including additional data in the response. Use in query: `include=currency_prices`." - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - }, - { - "schema": { - "type": "string", - "format": "date", - "example": "2011-12-17" - }, - "in": "query", - "name": "filter[start_date]", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns price points with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string", - "format": "date-time", - "example": "2019-06-07T17:20:06Z" - }, - "in": "query", - "name": "filter[start_datetime]", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns price points with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date." - }, - { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Price-Point-Type.yaml" - }, - "example": [ - "catalog", - "default", - "custom" - ], - "default": [ - "catalog", - "default" - ] - }, - "style": "form", - "explode": false, - "in": "query", - "name": "filter[type]", - "description": "Allows fetching price points with matching type. Use in query: `filter[type]=custom,catalog`." - }, - { - "$ref": "../components/parameters/sort-direction.yaml" - }, - { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [ - 1, - 2, - 3 - ] - }, - "in": "query", - "name": "filter[ids]", - "description": "Allows fetching price points with matching id based on provided values. Use in query: `filter[ids]=1,2,3`.", - "style": "form", - "explode": false - }, - { - "schema": { - "$ref": "../components/schemas/Include-Not-Null.yaml" - }, - "in": "query", - "name": "filter[archived_at]", - "description": "Allows fetching price points only if archived_at is present or not. Use in query: `filter[archived_at]=not_null`." - } - ] - } - }, - "/products_price_points.json": { - "get": { - "summary": "List All Products Price Points", - "tags": [ - "Product: Price Points" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/List-Product-Price-Points-Response.yaml" - }, - "examples": { - "example": { - "value": { - "price_points": [ - { - "id": 0, - "name": "My pricepoint", - "handle": "handle", - "price_in_cents": 10, - "interval": 5, - "interval_unit": "month", - "trial_price_in_cents": 10, - "trial_interval": 1, - "trial_interval_unit": "month", - "trial_type": "payment_expected", - "introductory_offer": true, - "initial_charge_in_cents": 0, - "initial_charge_after_trial": true, - "expiration_interval": 0, - "expiration_interval_unit": "month", - "product_id": 1230, - "created_at": "2021-04-02T17:52:09-04:00", - "updated_at": "2021-04-02T17:52:09-04:00", - "use_site_exchange_rate": true - } - ] - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "example": { - "value": { - "errors": [ - "date_field must be one of: created_at, updated_at", - "start_date supplied value is invalid, expected ISO 8601 format" - ] - } - } - } - } - } - } - }, - "operationId": "listAllProductPricePoints", - "description": "This method allows retrieval of a list of Products Price Points belonging to a Site.", - "x-operation-settings": { - "ErrorTemplates": { - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - }, - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/sort-direction.yaml" - }, - { - "schema": { - "$ref": "../components/schemas/Include-Null-Or-Not-Null.yaml" - }, - "in": "query", - "name": "filter[archived_at]", - "description": "Allows fetching price points only if archived_at is present or not. Use in query: `filter[archived_at]=not_null`." - }, - { - "schema": { - "$ref": "../components/schemas/Basic-Date-Field.yaml" - }, - "in": "query", - "description": "The type of filter you would like to apply to your search. Use in query: `filter[date_field]=created_at`.", - "name": "filter[date_field]" - }, - { - "schema": { - "type": "string", - "format": "date", - "example": "2019-06-07" - }, - "in": "query", - "name": "filter[end_date]", - "description": "The end date (format YYYY-MM-DD) with which to filter the date_field. Returns price points with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified." - }, - { - "schema": { - "type": "string", - "format": "date-time", - "example": "2019-06-07T17:20:06Z" - }, - "in": "query", - "name": "filter[end_datetime]", - "description": "The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns price points with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date." - }, - { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [ - 1, - 2, - 3 - ] - }, - "in": "query", - "name": "filter[ids]", - "style": "form", - "explode": false, - "description": "Allows fetching price points with matching id based on provided values. Use in query: `filter[ids]=1,2,3`." - }, - { - "schema": { - "type": "string", - "format": "date", - "example": "2019-06-07" - }, - "in": "query", - "description": "The start date (format YYYY-MM-DD) with which to filter the date_field. Returns price points with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified.", - "name": "filter[start_date]" - }, - { - "schema": { - "type": "string", - "format": "date-time", - "example": "2019-06-07T17:20:06Z" - }, - "in": "query", - "name": "filter[start_datetime]", - "description": "The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns price points with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date." - }, - { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Price-Point-Type.yaml" - }, - "default": [ - "catalog", - "default" - ], - "example": [ - "catalog", - "default", - "custom" - ] - }, - "style": "form", - "explode": false, - "in": "query", - "name": "filter[type]", - "description": "Allows fetching price points with matching type. Use in query: `filter[type]=catalog,custom`." - }, - { - "schema": { - "$ref": "../components/schemas/List-Products-Price-Points-Include.yaml" - }, - "in": "query", - "name": "include", - "description": "Allows including additional data in the response. Use in query: `include=currency_prices`." - }, - { - "$ref": "../components/parameters/page.yaml" - }, - { - "$ref": "../components/parameters/per-page.yaml" - } - ] - } - }, - "/subscriptions/{subscription_id}/activate.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "put": { - "summary": "Activate Subscription", - "tags": [ - "Subscriptions" - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Subscription-Response.yaml" - } - } - } - }, - "400": { - "description": "Bad Request", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-Array-Map-Response.yaml" - }, - "examples": { - "Generic error": { - "value": { - "errors": { - "base": [ - "Purchase Declined. The subscription is now in the 'awaiting_signup' state." - ] - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "400": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "activateSubscription", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Activate-Subscription-Request.yaml" - } - } - } - }, - "description": "Chargify offers the ability to activate awaiting signup and trialing subscriptions. This feature is only available on the Relationship Invoicing architecture. Subscriptions in a group may not be activated immediately.\n\nFor details on how the activation works, and how to activate subscriptions through the application, see [activation](#).\n\nThe `revert_on_failure` parameter controls the behavior upon activation failure.\n- If set to `true` and something goes wrong i.e. payment fails, then Chargify will not change the subscription's state. The subscription’s billing period will also remain the same.\n- If set to `false` and something goes wrong i.e. payment fails, then Chargify will continue through with the activation and enter an end of life state. For trialing subscriptions, that will either be trial ended (if the trial is no obligation), past due (if the trial has an obligation), or canceled (if the site has no dunning strategy, or has a strategy that says to cancel immediately). For awaiting signup subscriptions, that will always be canceled.\n\nThe default activation failure behavior can be configured per activation attempt, or you may set a default value under Config > Settings > Subscription Activation Settings.\n\n## Activation Scenarios\n\n### Activate Awaiting Signup subscription\n\n- Given you have a product without trial\n- Given you have a site without dunning strategy\n\n```mermaid\n flowchart LR\n AS[Awaiting Signup] --> A{Activate}\n A -->|Success| Active\n A -->|Failure| ROF{revert_on_failure}\n ROF -->|true| AS\n ROF -->|false| Canceled\n```\n\n- Given you have a product with trial\n- Given you have a site with dunning strategy\n\n```mermaid\n flowchart LR\n AS[Awaiting Signup] --> A{Activate}\n A -->|Success| Trialing\n A -->|Failure| ROF{revert_on_failure}\n ROF -->|true| AS\n ROF -->|false| PD[Past Due]\n```\n\n### Activate Trialing subscription\n\nYou can read more about the behavior of trialing subscriptions [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404494617357#trialing-subscriptions-0-0).\nWhen the `revert_on_failure` parameter is set to `true`, the subscription's state will remain as Trialing, we will void the invoice from activation and return any prepayments and credits applied to the invoice back to the subscription.\n" - } - }, - "/subscriptions/proforma_invoices.json": { - "post": { - "summary": "Create signup proforma invoice", - "tags": [ - "Proforma Invoices" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Proforma-Invoice.yaml" - } - } - } - }, - "400": { - "description": "Bad Request", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Proforma-Bad-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": { - "subscription": { - "base": [ - "must be an object" - ] - } - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-Array-Map-Response.yaml" - }, - "examples": { - "Product invalid": { - "value": { - "errors": { - "base": [ - "Couldn't find Product by 1" - ] - } - } - }, - "Missing customer": { - "value": { - "errors": { - "customer": [ - "Missing required customer attributes" - ] - } - } - }, - "Invalid type": { - "value": { - "errors": { - "base": [ - "currency must be a string" - ] - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "400": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "createSignupProformaInvoice", - "description": "This endpoint is only available for Relationship Invoicing sites. It cannot be used to create consolidated proforma invoices or preview prepaid subscriptions.\n\nCreate a proforma invoice to preview costs before a subscription's signup. Like other proforma invoices, it can be emailed to the customer, voided, and publicly viewed on the chargifypay domain.\n\nPass a payload that resembles a subscription create or signup preview request. For example, you can specify components, coupons/a referral, offers, custom pricing, and an existing customer or payment profile to populate a shipping or billing address.\n\nA product and customer first name, last name, and email are the minimum requirements. We recommend associating the proforma invoice with a customer_id to easily find their proforma invoices, since the subscription_id will always be blank.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Subscription-Request.yaml" - }, - "examples": { - "Minimum payload": { - "value": { - "subscription": { - "product_handle": "gold-product", - "customer_attributes": { - "first_name": "Myra", - "last_name": "Maisel", - "email": "mmaisel@example.com" - } - } - } - }, - "Minimum payload with referenced customer": { - "value": { - "subscription": { - "product_handle": "gold-product", - "customer_id": 12345 - } - } - } - } - } - } - } - }, - "parameters": [] - }, - "/subscriptions/proforma_invoices/preview.json": { - "post": { - "summary": "Create signup proforma preview", - "tags": [ - "Proforma Invoices" - ], - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Signup-Proforma-Preview-Response.yaml" - } - } - } - }, - "400": { - "description": "Bad Request", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Proforma-Bad-Response.yaml" - }, - "examples": { - "Example": { - "value": { - "errors": { - "subscription": { - "base": [ - "must be an object" - ] - } - } - } - } - } - } - } - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-Array-Map-Response.yaml" - }, - "examples": { - "Missing product": { - "value": { - "errors": { - "base": [ - "Couldn't find Product by 6067" - ] - } - } - }, - "Missing customer": { - "value": { - "errors": { - "customer": [ - "Missing required customer attributes" - ] - } - } - }, - "Invalid type": { - "value": { - "errors": { - "base": [ - "organization must be a string" - ] - } - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "400": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "previewSignupProformaInvoice", - "description": "This endpoint is only available for Relationship Invoicing sites. It cannot be used to create consolidated proforma invoice previews or preview prepaid subscriptions.\n\nCreate a signup preview in the format of a proforma invoice to preview costs before a subscription's signup. You have the option of optionally previewing the first renewal's costs as well. The proforma invoice preview will not be persisted.\n\nPass a payload that resembles a subscription create or signup preview request. For example, you can specify components, coupons/a referral, offers, custom pricing, and an existing customer or payment profile to populate a shipping or billing address.\n\nA product and customer first name, last name, and email are the minimum requirements.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Create-Subscription-Request.yaml" - }, - "examples": { - "Minimum example": { - "value": { - "subscription": { - "product_handle": "gold-plan", - "customer_attributes": { - "first_name": "first", - "last_name": "last", - "email": "flast@example.com" - } - } - } - }, - "Minimum example with existing customer": { - "value": { - "subscription": { - "product_handle": "silver-plan", - "customer_id": 1234 - } - } - } - } - } - }, - "description": "" - }, - "parameters": [ - { - "schema": { - "$ref": "../components/schemas/Create-Signup-Proforma-Preview-Include.yaml" - }, - "in": "query", - "name": "include", - "description": "Choose to include a proforma invoice preview for the first renewal. Use in query `include=next_proforma_invoice`." - } - ] - } - }, - "/api_exports/proforma_invoices/{batch_id}/rows.json": { - "parameters": [ - { - "$ref": "../components/parameters/batch-id-path.yaml" - } - ], - "get": { - "summary": "List Exported Proforma Invoices", - "tags": [ - "API Exports" - ], - "operationId": "listExportedProformaInvoices", - "description": "This API returns an array of exported proforma invoices for a provided `batch_id`. Pay close attention to pagination in order to control responses from the server.\n\nExample: `GET https://{subdomain}.chargify.com/api_exports/proforma_invoices/123/rows?per_page=10000&page=1`.", - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - }, - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/per-page-export.yaml" - }, - { - "$ref": "../components/parameters/page.yaml" - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Proforma-Invoice.yaml" - } - } - } - } - }, - "404": { - "description": "Not Found" - } - } - } - }, - "/api_exports/invoices/{batch_id}/rows.json": { - "parameters": [ - { - "$ref": "../components/parameters/batch-id-path.yaml" - } - ], - "get": { - "summary": "List Exported Invoices", - "tags": [ - "API Exports" - ], - "operationId": "listExportedInvoices", - "description": "This API returns an array of exported invoices for a provided `batch_id`. Pay close attention to pagination in order to control responses from the server.\n\nExample: `GET https://{subdomain}.chargify.com/api_exports/invoices/123/rows?per_page=10000&page=1`.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Invoice.yaml" - } - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - }, - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/per-page-export.yaml" - }, - { - "$ref": "../components/parameters/page.yaml" - } - ] - } - }, - "/api_exports/subscriptions/{batch_id}/rows.json": { - "parameters": [ - { - "$ref": "../components/parameters/batch-id-path.yaml" - } - ], - "get": { - "summary": "List Exported Subscriptions", - "tags": [ - "API Exports" - ], - "operationId": "listExportedSubscriptions", - "description": "This API returns an array of exported subscriptions for a provided `batch_id`. Pay close attention to pagination in order to control responses from the server.\n\nExample: `GET https://{subdomain}.chargify.com/api_exports/subscriptions/123/rows?per_page=200&page=1`.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "../components/schemas/Subscription.yaml" - } - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - }, - "collectParameters": true - }, - "parameters": [ - { - "$ref": "../components/parameters/per-page-export.yaml" - }, - { - "$ref": "../components/parameters/page.yaml" - } - ] - } - }, - "/api_exports/proforma_invoices.json": { - "post": { - "summary": "Create Proforma Invoices Export", - "tags": [ - "API Exports" - ], - "operationId": "exportProformaInvoices", - "description": "This API creates a proforma invoices export and returns a batchjob object.\n\nIt is only available for Relationship Invoicing architecture.", - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Batch-Job-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Single-Error-Response.yaml" - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "409": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - } - } - }, - "/api_exports/invoices.json": { - "post": { - "summary": "Create Invoices Export", - "tags": [ - "API Exports" - ], - "operationId": "exportInvoices", - "description": "This API creates an invoices export and returns a batchjob object.", - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Batch-Job-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Single-Error-Response.yaml" - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "409": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - } - }, - "parameters": [] - }, - "/api_exports/subscriptions.json": { - "post": { - "summary": "Create Subscriptions Export", - "tags": [ - "API Exports" - ], - "operationId": "exportSubscriptions", - "description": "This API creates a subscriptions export and returns a batchjob object.", - "responses": { - "201": { - "description": "Created", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Batch-Job-Response.yaml" - } - } - } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Single-Error-Response.yaml" - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "409": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - } - }, - "parameters": [] - }, - "/api_exports/proforma_invoices/{batch_id}.json": { - "parameters": [ - { - "$ref": "../components/parameters/batch-id-path.yaml" - } - ], - "get": { - "summary": "Read Proforma Invoices Export", - "tags": [ - "API Exports" - ], - "operationId": "readProformaInvoicesExport", - "description": "This API returns a batchjob object for proforma invoices export.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Batch-Job-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - } - } - }, - "/api_exports/invoices/{batch_id}.json": { - "parameters": [ - { - "$ref": "../components/parameters/batch-id-path.yaml" - } - ], - "get": { - "summary": "Read Invoices Export", - "tags": [ - "API Exports" - ], - "operationId": "readInvoicesExport", - "description": "This API returns a batchjob object for invoices export.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Batch-Job-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - } - } - }, - "/api_exports/subscriptions/{batch_id}.json": { - "parameters": [ - { - "$ref": "../components/parameters/batch-id-path.yaml" - } - ], - "get": { - "summary": "Read Subscriptions Export", - "tags": [ - "API Exports" - ], - "operationId": "readSubscriptionsExport", - "description": "This API returns a batchjob object for subscriptions export.", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/Batch-Job-Response.yaml" - } - } - } - }, - "404": { - "description": "Not Found" - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'" - } - } - } - }, - "/subscriptions/{subscription_id}/request_payment_profiles_update.json": { - "parameters": [ - { - "$ref": "../components/parameters/subscription-id-path.yaml" - } - ], - "post": { - "summary": "Send request payment update email", - "tags": [ - "Payment Profiles" - ], - "responses": { - "201": { - "description": "Created" - }, - "404": { - "description": "Not Found" - }, - "422": { - "description": "Unprocessable Entity (WebDAV)", - "content": { - "application/json": { - "schema": { - "$ref": "../components/schemas/errors/Error-List-Response.yaml" - }, - "examples": { - "Too many requests": { - "value": { - "errors": [ - "Too many requests. You can perform 5 requests within 00:30:00" - ] - } - } - } - } - } - } - }, - "x-operation-settings": { - "ErrorTemplates": { - "404": "Not Found:'{$response.body}'", - "422": "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'." - } - }, - "operationId": "sendRequestUpdatePaymentEmail", - "description": "You can send a \"request payment update\" email to the customer associated with the subscription.\n\nIf you attempt to send a \"request payment update\" email more than five times within a 30-minute period, you will receive a `422` response with an error message in the body. This error message will indicate that the request has been rejected due to excessive attempts, and will provide instructions on how to resubmit the request.\n\nAdditionally, if you attempt to send a \"request payment update\" email for a subscription that does not exist, you will receive a `404` error response. This error message will indicate that the subscription could not be found, and will provide instructions on how to correct the error and resubmit the request.\n\nThese error responses are designed to prevent excessive or invalid requests, and to provide clear and helpful information to users who encounter errors during the request process." - } - } - }, - "servers": [ - { - "url": "https://{subdomain}.{domain}", - "description": "Production server", - "variables": { - "subdomain": { - "default": "subdomain", - "description": "The subdomain for your Chargify site." - }, - "domain": { - "default": "chargify.com", - "description": "The Chargify server domain." - } - } - } - ], - "security": [ - { - "BasicAuth": [] - } - ], - "components": { - "securitySchemes": { - "BasicAuth": { - "type": "http", - "scheme": "basic", - "description": "The `username` is a Maxio Advanced Billing API key. The `password` is `x`." - } - }, - "schemas": { - "Invoice-Event-Payment": { - "title": "Invoice Event Payment", - "type": "object", - "description": "A nested data structure detailing the method of payment", - "anyOf": [ - { - "$ref": "#/components/schemas/Payment-Method-Apple-Pay" - }, - { - "$ref": "#/components/schemas/Payment-Method-Bank-Account" - }, - { - "$ref": "#/components/schemas/Payment-Method-Credit-Card" - }, - { - "$ref": "#/components/schemas/Payment-Method-External" - }, - { - "$ref": "#/components/schemas/Payment-Method-Paypal" - } - ], - "discriminator": { - "propertyName": "type", - "mapping": { - "apple_pay": "#/components/schemas/Payment-Method-Apple-Pay", - "bank_account": "#/components/schemas/Payment-Method-Bank-Account", - "credit_card": "#/components/schemas/Payment-Method-Credit-Card", - "external": "#/components/schemas/Payment-Method-External", - "paypal_account": "#/components/schemas/Payment-Method-Paypal" - } - } - }, - "Payment-Method-Apple-Pay": { - "$ref": "../components/schemas/invoice_event_specific_data/Payment-Method-Apple-Pay.yaml" - }, - "Payment-Method-Bank-Account": { - "$ref": "../components/schemas/invoice_event_specific_data/Payment-Method-Bank-Account.yaml" - }, - "Payment-Method-Credit-Card": { - "$ref": "../components/schemas/invoice_event_specific_data/Payment-Method-Credit-Card.yaml" - }, - "Payment-Method-External": { - "$ref": "../components/schemas/invoice_event_specific_data/Payment-Method-External.yaml" - }, - "Payment-Method-Paypal": { - "$ref": "../components/schemas/invoice_event_specific_data/Payment-Method-Paypal.yaml" - } - } - } -} \ No newline at end of file diff --git a/src/openapi.json b/src/openapi.json deleted file mode 100644 index 59fdaf4..0000000 --- a/src/openapi.json +++ /dev/null @@ -1,1999 +0,0 @@ -{ - "openapi": "3.1.0", - "info": { - "title": "Ocean.io API Documentation", - "summary": "Welcome to Ocean.io's API.", - "description": "\n Welcome to Ocean.io's API.\n The API can be used to access all our API endpoints, such as our enrich API to look up company information, or our discover API to identify companies based on specific search criteria such as semantic similarity, technologies or industries.\n Ocean.io's APIs are a set of HTTPS endpoints that you can use to retrieve and integrate Ocean.io's data into your existing workflows.\n All requests should be made through https and the request and response bodies should be formatted in JSON.\n ", - "version": "2.0.0", - "x-logo": { "url": "https://cdn.ocean.io/assets/images/logo/256x92_ocean-logo.svg" } - }, - "servers": [{ "url": "https://api.ocean.io" }], - "paths": { - "/v2/search/companies": { - "post": { - "tags": ["Search"], - "summary": "Lookalike companies search", - "description": "Search companies using filters", - "operationId": "searchCompanies", - "parameters": [ - { - "name": "apiToken", - "in": "query", - "required": true, - "schema": { "type": "string", "title": "Apitoken" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/PublicSearchCompaniesBody" } - } - } - }, - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/PublicSearchCompaniesResult" } - } - } - }, - "404": { "description": "Not found" }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/HTTPValidationError" } - } - } - } - } - } - }, - "/v2/enrich/company": { - "post": { - "tags": ["Enrich"], - "summary": "Enrich company", - "description": "Match a company with our database and enrich it with additional information", - "operationId": "enrichCompany", - "parameters": [ - { - "name": "apiToken", - "in": "query", - "required": true, - "schema": { "type": "string", "title": "Apitoken" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { "schema": { "$ref": "#/components/schemas/MatchCompanyBody" } } - } - }, - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { "schema": { "$ref": "#/components/schemas/PublicCompany" } } - } - }, - "404": { "description": "Not found" }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/HTTPValidationError" } - } - } - } - } - } - }, - "/v2/enrich/person": { - "post": { - "tags": ["Enrich"], - "summary": "Enrich person", - "description": "Match a person with our database and enrich it with additional information", - "operationId": "enrichPerson", - "parameters": [ - { - "name": "apiToken", - "in": "query", - "required": true, - "schema": { "type": "string", "title": "Apitoken" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { "schema": { "$ref": "#/components/schemas/MatchPersonBody" } } - } - }, - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { "schema": { "$ref": "#/components/schemas/PublicPerson" } } - } - }, - "404": { "description": "Not found" }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/HTTPValidationError" } - } - } - } - } - } - }, - "/v2/data-fields": { - "get": { - "tags": ["Data"], - "summary": "Get list of available industries, technologies and regions", - "description": "Provides a list of all industries and industry categories, technologies and regions searchable by Ocean.io.", - "operationId": "getDataFieldsPublic", - "parameters": [ - { - "name": "apiToken", - "in": "query", - "required": true, - "schema": { "type": "string", "title": "Apitoken" } - } - ], - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/PublicGetDataFieldsResponse" } - } - } - }, - "404": { "description": "Not found" }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/HTTPValidationError" } - } - } - } - } - } - }, - "/v2/search/people": { - "post": { - "tags": ["Search"], - "summary": "Search people", - "description": "Search people using filters", - "operationId": "searchPeople", - "parameters": [ - { - "name": "apiToken", - "in": "query", - "required": true, - "schema": { "type": "string", "title": "Apitoken" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/PublicSearchPeopleBody" } - } - } - }, - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/PublicSearchPeopleResult" } - } - } - }, - "404": { "description": "Not found" }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/HTTPValidationError" } - } - } - } - } - } - }, - "/v2/credits/balance": { - "get": { - "tags": ["Credits"], - "summary": "Get credit balance", - "description": "Get credit balance", - "operationId": "getCreditBalance", - "parameters": [ - { - "name": "apiToken", - "in": "query", - "required": true, - "schema": { "type": "string", "title": "Apitoken" } - } - ], - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/GetCreditBalanceResponse" } - } - } - }, - "404": { "description": "Not found" }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/HTTPValidationError" } - } - } - } - } - } - }, - "/internal/credits/balance": { - "get": { - "tags": ["Credits"], - "summary": "Get credit balance internal", - "description": "Get credit balance internal", - "operationId": "getCreditBalanceInternal", - "security": [{ "HTTPBearer": [] }], - "parameters": [ - { - "name": "organizationId", - "in": "query", - "required": false, - "schema": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Organizationid" - } - } - ], - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/GetCreditBalanceResponse" } - } - } - }, - "404": { "description": "Not found" }, - "422": { - "description": "Validation Error", - "content": { - "application/json": { - "schema": { "$ref": "#/components/schemas/HTTPValidationError" } - } - } - } - } - } - } - }, - "components": { - "schemas": { - "CompaniesFilters": { - "properties": { - "lookalikeDomains": { - "anyOf": [ - { "items": { "type": "string" }, "type": "array", "maxItems": 10 }, - { "type": "null" } - ], - "title": "Similar domains", - "description": "Find domains similar to the provided", - "examples": [["bestcustomer.com", "idealcustomer.com"]] - }, - "minScore": { - "anyOf": [ - { "type": "number", "exclusiveMaximum": 1.0, "exclusiveMinimum": 0.0 }, - { "type": "null" } - ], - "title": "Minimum score", - "description": "Minimum score for companies to appear in the results.", - "default": 0.79, - "examples": [0.95] - }, - "includeDomains": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Domains to include", - "description": "Only return specified domains", - "examples": [["interesting.com", "amazing.com"]] - }, - "excludeDomains": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Domains to exclude", - "description": "Exclude specified domains from the results", - "examples": [["boring.com", "useless.com"]] - }, - "companySizes": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/PublicCompanySize" }, "type": "array" }, - { "type": "null" } - ], - "title": "Company size", - "description": "Filter by company size ranges", - "examples": [["2-10", "51-200", "100001-500000"]] - }, - "ecommerce": { - "anyOf": [{ "type": "boolean" }, { "type": "null" }], - "title": "E-commerce", - "description": "true -> returns only e-commerce companies
false -> excludes e-commerce companies
none -> returns everything", - "examples": [true, false] - }, - "socialMedias": { - "anyOf": [{ "$ref": "#/components/schemas/SocialMediasFilter" }, { "type": "null" }], - "title": "Social medias", - "description": "Filter by social media presence", - "examples": [{ "medias": ["linkedin", "facebook"], "mode": "anyOf" }] - }, - "yearFounded": { - "anyOf": [{ "$ref": "#/components/schemas/FromTo" }, { "type": "null" }], - "title": "Year founded", - "description": "Filter by year founded", - "examples": [{ "from": 1960, "to": 1990 }] - }, - "countriesCount": { - "anyOf": [{ "$ref": "#/components/schemas/FromTo" }, { "type": "null" }], - "title": "Countries count", - "description": "Filter by the number of countries in which the company operates", - "examples": [{ "from": 1, "to": 5 }] - }, - "revenues": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/Revenue" }, "type": "array" }, - { "type": "null" } - ], - "title": "Revenue", - "description": "Filter by revenue ranges", - "examples": [["0-1M", "1-10M", ">1000M"]] - }, - "employeeCountOcean": { - "anyOf": [{ "$ref": "#/components/schemas/FromTo" }, { "type": "null" }], - "title": "Employee count", - "description": "Only return companies that have a certain number of employee profiles in our database", - "examples": [{ "from": 10, "to": 100 }] - }, - "webTrafficVisits": { - "anyOf": [{ "$ref": "#/components/schemas/FromTo" }, { "type": "null" }], - "title": "Web traffic visits", - "description": "Only return companies that have a certain amount of visits", - "examples": [{ "from": 1000, "to": 10000 }] - }, - "mobileApps": { - "anyOf": [{ "$ref": "#/components/schemas/FromTo" }, { "type": "null" }], - "title": "Number of mobile apps", - "description": "Filter by the number of mobile apps that the company produced", - "examples": [{ "from": 1, "to": 5 }] - }, - "headquarterGeolocation": { - "anyOf": [{ "$ref": "#/components/schemas/GeolocationFilter" }, { "type": "null" }], - "title": "Headquarter location", - "description": "Filter by headquarter location", - "examples": [{ "latitude": 38.880817, "longitude": -77.10216, "radius": 1000 }] - }, - "geolocation": { - "anyOf": [{ "$ref": "#/components/schemas/GeolocationFilter" }, { "type": "null" }], - "title": "Other locations", - "description": "Filter by non-headquarter locations", - "examples": [{ "latitude": 50.83348, "longitude": -0.1410065, "radius": 5000 }] - }, - "locationsCount": { - "anyOf": [{ "$ref": "#/components/schemas/FromTo" }, { "type": "null" }], - "title": "Locations count", - "description": "Only return companies that have a certain amount of locations", - "examples": [{ "from": 5, "to": 10 }] - }, - "departmentSizes": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/DepartmentSizeFilter" }, "type": "array" }, - { "type": "null" } - ], - "title": "Department size filter", - "description": "Filter by the size of company departments", - "examples": [[{ "department": "Accounting and Finance", "from": 5, "to": 10 }]] - }, - "keywords": { - "anyOf": [{ "$ref": "#/components/schemas/KeywordsFilter" }, { "type": "null" }], - "title": "Keywords filter", - "description": "Filter by keywords", - "examples": [{ "keywords": ["premium copy paper", "paper"], "mode": "anyOf" }] - }, - "states": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/State" }, "type": "array" }, - { "type": "null" } - ], - "title": "State filter", - "description": "Filter by country states (if applicable)", - "examples": [ - [ - { "abbreviation": "ca", "country": "us" }, - { "abbreviation": "yt", "country": "ca" } - ] - ] - }, - "employeeCountLinkedin": { - "anyOf": [{ "$ref": "#/components/schemas/FromTo" }, { "type": "null" }], - "title": "Employee count on LinkedIn", - "description": "The number of employees a company has on LinkedIn", - "examples": [{ "from": 50, "to": 100 }] - }, - "countries": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Countries", - "description": "Filter by **all** countries where the company has presence.
Must be provided as alpha-2 ISO 3166 country codes.
`[\"es\", \"pt\"]` means Spain (primary/not primary) **OR** Portugal (primary/not primary).
if additional filter `primaryCountries = [\"de\"]` is used then it means:
(Spain (not primary) **OR** Portugal (not primary)) **AND** Germany (primary)", - "examples": [["es", "pt"]] - }, - "primaryCountries": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Primary countries", - "description": "Filter only by **primary** countries where the company has presence.
Must be provided as alpha-2 ISO 3166 country codes.
`countries = [\"de\", \"at\"]` means Germany (primary) **OR** Austria (primary).
if additional filter `countries = [\"es\"]` is used then it means:
(Germany (primary) **OR** Austria (primary)) **AND** Spain (not primary)", - "examples": [["de"]] - }, - "industries": { - "anyOf": [{ "$ref": "#/components/schemas/IndustriesFilter" }, { "type": "null" }], - "title": "Industries", - "description": "Filter by company industries. Available values are located at */v2/data-fields* endpoint.
", - "examples": [{ "industries": ["Advertising Platforms", "Biopharma"], "mode": "anyOf" }] - }, - "industryCategories": { - "anyOf": [ - { "$ref": "#/components/schemas/IndustryCategoriesFilter" }, - { "type": "null" } - ], - "title": "Industry categories", - "description": "Filter by company industry categories. Available values are located at */v2/data-fields* endpoint.
", - "examples": [{ "industryCategories": ["Real Estate", "Hardware"], "mode": "anyOf" }] - }, - "technologies": { - "anyOf": [{ "$ref": "#/components/schemas/TechnologiesFilter" }, { "type": "null" }], - "title": "Technologies", - "description": "Filter by software technologies used by the company. Available values are located at */v2/data-fields* endpoint.
", - "examples": [{ "mode": "anyOf", "technologies": ["Amazon Advertising", "Google Maps"] }] - } - }, - "additionalProperties": false, - "type": "object", - "title": "CompaniesFilters" - }, - "Company": { - "properties": { - "name": { - "type": "string", - "title": "Company name", - "description": "The name of the company", - "examples": ["Ocean ApS"] - }, - "registrationNumber": { - "type": "string", - "title": "Registration number", - "description": "The registration number of the company", - "examples": ["123456789"] - }, - "email": { - "type": "string", - "title": "Email", - "description": "The email of the company", - "examples": ["hello@ocean.io"] - }, - "phone": { - "type": "string", - "title": "Phone", - "description": "The phone number of the company", - "examples": ["+45 12345678"] - }, - "countryCode": { - "type": "string", - "title": "Country code", - "description": "Country code of the company's headquarters", - "examples": ["dk"] - }, - "state": { - "type": "string", - "title": "State", - "description": "Name of the state/region where the company is located", - "examples": ["Arkansas"] - }, - "city": { - "type": "string", - "title": "City", - "description": "The city where the company is located", - "examples": ["Copenhagen"] - }, - "streetAddress": { - "type": "string", - "title": "Street address", - "description": "Street address of the company", - "examples": ["Strandgade 6"] - }, - "postalCode": { - "type": "string", - "title": "Postal code", - "description": "The postal code of the company", - "examples": ["1401"] - }, - "address": { - "type": "string", - "title": "Address", - "description": "Full address of the company", - "examples": ["Strandgade 6, 1401 Copenhagen"] - }, - "facebook": { - "type": "string", - "title": "Facebook", - "description": "The Facebook page of the company", - "examples": ["https://www.facebook.com/oceanio"] - }, - "twitter": { - "type": "string", - "title": "Twitter", - "description": "Company's Twitter page", - "examples": ["https://twitter.com/oceanio"] - }, - "linkedin": { - "type": "string", - "title": "LinkedIn", - "description": "LinkedIn page of the company", - "examples": ["https://www.linkedin.com/company/oceanio"] - }, - "instagram": { - "type": "string", - "title": "Instagram", - "description": "Instagram page of the company", - "examples": ["https://www.instagram.com/oceanio"] - }, - "xing": { - "type": "string", - "title": "Xing", - "description": "The Xing page of the company", - "examples": ["https://www.xing.com/oceanio"] - }, - "domain": { - "type": "string", - "title": "Domain", - "description": "The domain name of the company's website", - "examples": ["ocean.io"] - }, - "youtube": { - "type": "string", - "title": "YouTube", - "description": "The YouTube page of the company", - "examples": ["https://www.youtube.com/oceanio"] - } - }, - "additionalProperties": false, - "type": "object", - "title": "Company" - }, - "ContactNumber": { - "properties": { - "number": { "type": "string", "title": "Number", "description": "Contact number" }, - "country": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Contact number country code", - "description": "Country code of the contact number" - }, - "primary": { - "type": "boolean", - "title": "Primary contact number", - "description": "True if the contact number is the primary contact number of the company" - } - }, - "type": "object", - "required": ["number"], - "title": "ContactNumber" - }, - "Credits": { - "properties": { - "standard": { - "type": "integer", - "title": "Standard", - "description": "Number of 'standard' credits left.", - "default": 0 - }, - "email": { - "type": "integer", - "title": "Email", - "description": "Number of 'email' credits left.", - "default": 0 - } - }, - "type": "object", - "title": "Credits" - }, - "Department": { - "type": "string", - "enum": [ - "Accounting and Finance", - "Board", - "Business Support", - "Customer Relations", - "Design", - "Editorial Personnel", - "Engineering", - "Founder/Owner", - "Healthcare", - "HR", - "Legal", - "Management", - "Manufacturing", - "Marketing and Advertising", - "Operations", - "PR and Communications", - "Procurement", - "Product", - "Quality Control", - "R&D", - "Sales", - "Security", - "Supply Chain", - "Other" - ], - "title": "Department" - }, - "DepartmentSize": { - "properties": { - "department": { - "allOf": [{ "$ref": "#/components/schemas/Department" }], - "description": "Department name" - }, - "size": { "type": "integer", "title": "Size", "description": "Department size" } - }, - "type": "object", - "required": ["department", "size"], - "title": "DepartmentSize" - }, - "DepartmentSizeFilter": { - "properties": { - "from": { - "anyOf": [{ "type": "integer", "minimum": 0.0 }, { "type": "null" }], - "title": "Greater than or equal to", - "description": "Greater than or equal to" - }, - "to": { - "anyOf": [{ "type": "integer", "minimum": 0.0 }, { "type": "null" }], - "title": "Less than or equal to", - "description": "Less than or equal to" - }, - "department": { "$ref": "#/components/schemas/Department" } - }, - "additionalProperties": false, - "type": "object", - "required": ["department"], - "title": "DepartmentSizeFilter" - }, - "FromTo": { - "properties": { - "from": { - "anyOf": [{ "type": "integer", "minimum": 0.0 }, { "type": "null" }], - "title": "Greater than or equal to", - "description": "Greater than or equal to" - }, - "to": { - "anyOf": [{ "type": "integer", "minimum": 0.0 }, { "type": "null" }], - "title": "Less than or equal to", - "description": "Less than or equal to" - } - }, - "additionalProperties": false, - "type": "object", - "title": "FromTo" - }, - "GeolocationFilter": { - "properties": { - "latitude": { - "type": "number", - "title": "Latitude", - "description": "Latitude of the location" - }, - "longitude": { - "type": "number", - "title": "Longitude", - "description": "Longitude of the location" - }, - "radius": { "type": "integer", "title": "Radius", "description": "Radius in meters" } - }, - "additionalProperties": false, - "type": "object", - "required": ["latitude", "longitude", "radius"], - "title": "GeolocationFilter" - }, - "GetCreditBalanceResponse": { - "properties": { - "oneTimeCredits": { - "allOf": [{ "$ref": "#/components/schemas/Credits" }], - "description": "One-time credits balance.", - "examples": [{ "email": 100, "standard": 100 }] - } - }, - "type": "object", - "title": "GetCreditBalanceResponse" - }, - "HTTPValidationError": { - "properties": { - "detail": { - "items": { "$ref": "#/components/schemas/ValidationError" }, - "type": "array", - "title": "Detail" - } - }, - "type": "object", - "title": "HTTPValidationError" - }, - "Impressum": { - "properties": { - "company": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Company name", - "description": "Company name as mentioned in Impressum", - "examples": ["Dunder Mifflin Paper Company, Inc."] - }, - "address": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Address", - "description": "Company address as mentioned in Impressum", - "examples": ["Scranton Business Park, 1725 Slough Ave Suit 200, Scranton, USA"] - }, - "email": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Email", - "description": "Company email as mentioned in Impressum", - "examples": ["email@dundermifflin.com"] - }, - "phone": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Phone", - "description": "Company phone as mentioned in Impressum", - "examples": ["+35123456789"] - }, - "fax": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Fax", - "description": "Company fax as mentioned in Impressum", - "examples": ["+35123456790"] - }, - "vat": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "VAT", - "description": "VAT number as mentioned in Impressum", - "examples": ["123456"] - }, - "url": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Impressum url", - "description": "url where Impressum can be found", - "examples": ["https://dundermifflinpaper.com/impressum"] - }, - "people": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/ImpressumPerson" }, "type": "array" }, - { "type": "null" } - ], - "title": "People", - "description": "People mentioned in Impressum" - } - }, - "type": "object", - "title": "Impressum" - }, - "ImpressumPerson": { - "properties": { - "name": { "type": "string", "title": "Name", "examples": ["Michael Scott"] }, - "position": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Position", - "examples": ["Regional Manager"] - } - }, - "type": "object", - "required": ["name"], - "title": "ImpressumPerson" - }, - "IndustriesFilter": { - "properties": { - "industries": { - "items": { "type": "string" }, - "type": "array", - "title": "Industries", - "description": "Array of the industries to include" - }, - "mode": { - "type": "string", - "enum": ["anyOf", "allOf"], - "title": "Search mode", - "description": "[default] anyOf - match at least one of the industries
allOf - match all of the industries", - "default": "anyOf" - } - }, - "additionalProperties": false, - "type": "object", - "required": ["industries"], - "title": "IndustriesFilter" - }, - "IndustryCategoriesFilter": { - "properties": { - "industryCategories": { - "items": { "type": "string" }, - "type": "array", - "title": "Industry categories", - "description": "Array of the industry categories to include" - }, - "mode": { - "type": "string", - "enum": ["anyOf", "allOf"], - "title": "Search mode", - "description": "[default] anyOf - match at least one of the industry categories
allOf - match all of the industry categories", - "default": "anyOf" - } - }, - "additionalProperties": false, - "type": "object", - "required": ["industryCategories"], - "title": "IndustryCategoriesFilter" - }, - "KeywordsFilter": { - "properties": { - "keywords": { - "items": { "type": "string" }, - "type": "array", - "title": "Keywords", - "description": "Array of the keywords" - }, - "mode": { - "type": "string", - "enum": ["anyOf", "allOf", "noneOf"], - "title": "Search mode", - "description": "[default] anyOf - match at least one of the keywords
allOf - match all of the keywords
noneOf - match none of the keywords", - "default": "anyOf" - } - }, - "additionalProperties": false, - "type": "object", - "required": ["keywords"], - "title": "KeywordsFilter" - }, - "Location": { - "properties": { - "primary": { - "type": "boolean", - "title": "Primary location", - "description": "True if the location is the headquarter of the company", - "default": false, - "examples": [true, false] - }, - "latitude": { - "anyOf": [{ "type": "number" }, { "type": "null" }], - "title": "Latitude", - "description": "Latitude of the location", - "examples": [43.6471] - }, - "longitude": { - "anyOf": [{ "type": "number" }, { "type": "null" }], - "title": "Longitude", - "description": "Longitude of the location", - "examples": [-79.3971] - }, - "country": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Country code", - "description": "Country code of the location", - "examples": ["us"] - }, - "locality": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Locality/City", - "description": "Locality (city) of the location", - "examples": ["Scranton"] - }, - "region": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Region", - "description": "Region of the location", - "examples": ["Lackawanna County"] - }, - "postalCode": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Postal code", - "description": "Postal code of the location", - "examples": ["18505"] - }, - "streetAddress": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Street address", - "description": "Street address of the location", - "examples": ["Scranton Business Park, 1725 Slough Ave Suit 200"] - }, - "state": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "State", - "description": "ISO state abbreviation of the location (if applicable)", - "examples": ["pa"] - }, - "regionCode": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Region code", - "description": "Region code of the location", - "examples": ["PA"] - } - }, - "type": "object", - "title": "Location" - }, - "MatchCompanyBody": { - "properties": { - "company": { - "allOf": [{ "$ref": "#/components/schemas/Company" }], - "description": "The company to match with" - }, - "people": { - "items": { "$ref": "#/components/schemas/Person" }, - "type": "array", - "title": "People", - "description": "The people to match company with" - } - }, - "additionalProperties": false, - "type": "object", - "title": "MatchCompanyBody" - }, - "MatchPersonBody": { - "properties": { - "person": { - "allOf": [{ "$ref": "#/components/schemas/Person" }], - "description": "The person to match with" - }, - "company": { - "anyOf": [{ "$ref": "#/components/schemas/Company" }, { "type": "null" }], - "title": "Company", - "description": "The company to match the person with" - } - }, - "additionalProperties": false, - "type": "object", - "required": ["person"], - "title": "MatchPersonBody" - }, - "Media": { - "properties": { - "url": { "type": "string", "title": "Media URL", "description": "URL of the media" }, - "handle": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Handle", - "description": "ids extracted from social media urls" - }, - "name": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Name", - "description": "Name of the company as it appears in the social media account" - } - }, - "type": "object", - "required": ["url"], - "title": "Media" - }, - "Medias": { - "properties": { - "linkedin": { - "anyOf": [{ "$ref": "#/components/schemas/Media" }, { "type": "null" }], - "description": "LinkedIn page associated with the company", - "examples": [ - { - "handle": "dunder-mifflin", - "name": "Dunder Mifflin Paper Company, Inc.", - "url": "https://www.linkedin.com/company/dunder-mifflin" - } - ] - }, - "twitter": { - "anyOf": [{ "$ref": "#/components/schemas/Media" }, { "type": "null" }], - "description": "Twitter page associated with the company", - "examples": [ - { - "handle": "dunder-mifflin", - "name": "Dunder Mifflin Paper Company, Inc.", - "url": "https://twitter.com/dunder-mifflin" - } - ] - }, - "youtube": { - "anyOf": [{ "$ref": "#/components/schemas/Media" }, { "type": "null" }], - "description": "YouTube page associated with the company", - "examples": [ - { - "handle": "dunder-mifflin", - "name": "Dunder Mifflin Paper Company, Inc.", - "url": "https://youtube.com/channel/dunder-mifflin" - } - ] - }, - "facebook": { - "anyOf": [{ "$ref": "#/components/schemas/Media" }, { "type": "null" }], - "description": "Facebook page associated with the company", - "examples": [ - { - "handle": "dunder-mifflin", - "name": "Dunder Mifflin Paper Company, Inc.", - "url": "https://facebook.com/dunder-mifflin" - } - ] - }, - "xing": { - "anyOf": [{ "$ref": "#/components/schemas/Media" }, { "type": "null" }], - "description": "Xing page associated with the company", - "examples": [ - { - "handle": "dunder-mifflin", - "name": "Dunder Mifflin Paper Company, Inc.", - "url": "https://xing.com/dunder-mifflin" - } - ] - }, - "tiktok": { - "anyOf": [{ "$ref": "#/components/schemas/Media" }, { "type": "null" }], - "description": "TikTok page associated with the company", - "examples": [ - { - "handle": "dunder-mifflin", - "name": "Dunder Mifflin Paper Company, Inc.", - "url": "https://tiktok.com/dunder-mifflin" - } - ] - }, - "instagram": { - "anyOf": [{ "$ref": "#/components/schemas/Media" }, { "type": "null" }], - "description": "Instagram page associated with the company", - "examples": [ - { - "handle": "dunder-mifflin", - "name": "Dunder Mifflin Paper Company, Inc.", - "url": "https://instagram.com/dunder-mifflin" - } - ] - } - }, - "type": "object", - "title": "Medias" - }, - "MobileApp": { - "properties": { - "link": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "url", - "description": "Website address for this app", - "examples": ["https://www.my.app.com/"] - }, - "name": { - "type": "string", - "title": "App name", - "description": "App name", - "examples": ["My awesome app"] - } - }, - "type": "object", - "required": ["name"], - "title": "MobileApp" - }, - "PeopleFilters": { - "properties": { - "includeIds": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Ids to include", - "description": "Only return specified people. Note: this is not implemented yet.", - "examples": [["51e19df9c1d70c7c", "971b1b1bfb1ffb1a"]] - }, - "excludeIds": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Ids to exclude", - "description": "Exclude specified people from the results. Note: this is not implemented yet.", - "examples": [["51e19df9c1d70c7c", "971b1b1bfb1ffb1a"]] - }, - "seniorities": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/Seniority" }, "type": "array" }, - { "type": "null" } - ], - "title": "Seniorities", - "description": "Filter by seniorities. Available values are located at */v2/data-fields* endpoint.
", - "examples": [["Founder", "Owner"]] - }, - "jobTitles": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Jobtitles", - "description": "Filter by job title", - "examples": [["CEO", "CTO"]] - }, - "excludeJobTitles": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Excludejobtitles", - "description": "Exclude people by job title", - "examples": [["CEO", "CTO"]] - }, - "departments": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/Department" }, "type": "array" }, - { "type": "null" } - ], - "title": "Departments", - "description": "Filter by departments. Available values are located at */v2/data-fields* endpoint.
", - "examples": [["Management", "Marketing and Advertising"]] - }, - "countries": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Countries", - "description": "Filter by countries", - "examples": [["us", "dk"]] - }, - "names": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Names", - "description": "Filter by names", - "examples": [["John Doe", "Peter Pan"]] - }, - "emailStatuses": { - "anyOf": [ - { - "items": { - "type": "string", - "enum": ["verified", "guessed", "catchAll", "notAttempted"] - }, - "type": "array" - }, - { "type": "null" } - ], - "title": "Emailstatuses", - "description": "Filter by email status", - "examples": [["verified", "catchAll"]] - }, - "emails": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Emails", - "description": "Filter by email address", - "examples": [["email_1@domain.com", "email_2@domain.com"]] - }, - "keywords": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Keywords", - "description": "Filter people based on keywords from their summary", - "examples": [["engineering", "research"]] - } - }, - "additionalProperties": false, - "type": "object", - "title": "PeopleFilters" - }, - "Person": { - "properties": { - "id": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Person id", - "description": "Ocean id of the person", - "examples": ["b8952796be57982d"] - }, - "name": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Name", - "description": "Full name of the contact", - "examples": ["John Doe"] - }, - "firstName": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "First name", - "description": "First name of the contact", - "examples": ["John"] - }, - "lastName": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Last name", - "description": "Last name of the contact", - "examples": ["Doe"] - }, - "jobTitle": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Job title", - "description": "Job title of the contact", - "examples": ["CEO"] - }, - "email": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Email", - "description": "Email address of the contact", - "examples": ["john.doe@example.com"] - }, - "phone": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Phone", - "description": "Phone number of the contact", - "examples": ["+45 12345678"] - }, - "facebook": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Facebook", - "description": "Facebook page of the contact", - "examples": ["https://www.facebook.com/johndoe"] - }, - "twitter": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Twitter", - "description": "The Twitter page of the contact", - "examples": ["https://twitter.com/johndoe"] - }, - "linkedin": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "LinkedIn", - "description": "The LinkedIn page of the contact", - "examples": ["https://www.linkedin.com/in/johndoe"] - }, - "country": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Country", - "description": "The country of the contact", - "examples": ["dk"] - } - }, - "additionalProperties": false, - "type": "object", - "title": "Person" - }, - "PublicCompany": { - "properties": { - "domain": { - "type": "string", - "title": "Domain", - "description": "Domain of the company, used as a unique identifier", - "examples": ["dundermifflinpaper.com"] - }, - "countries": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Countries", - "description": "List of all countries in which the company operates", - "examples": [["us", "ca"]] - }, - "primaryCountry": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Primary country", - "description": "Main country of the company", - "examples": ["us"] - }, - "companySize": { - "anyOf": [{ "$ref": "#/components/schemas/PublicCompanySize" }, { "type": "null" }], - "title": "Company size range", - "description": "Company size range", - "examples": ["2-10"] - }, - "industryCategories": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Industrycategories", - "description": "Industry categories of the company
Available values can be found at */v2/data-fields* endpoint", - "examples": [["Consumer Electronics", "Hardware"]] - }, - "industries": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Industries", - "description": "Industries of the company
Available values can be found at */v2/data-fields* endpoint", - "examples": [["Audio", "Electronics"]] - }, - "ecommerce": { - "anyOf": [{ "type": "boolean" }, { "type": "null" }], - "title": "E-Commerce", - "description": "True if the company is an e-commerce company", - "examples": [true] - }, - "keywords": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Keywords", - "description": "Keywords associated with the company", - "examples": [["paper", "premium copy paper"]] - }, - "employeeCountOcean": { - "anyOf": [{ "type": "integer" }, { "type": "null" }], - "title": "Employeecountocean", - "description": "Number of people working at the company in our database.", - "examples": [57] - }, - "employeeCountLinkedin": { - "anyOf": [{ "type": "integer" }, { "type": "null" }], - "title": "Employeecountlinkedin", - "description": "Number of people linked to the company page on Linkedin. This number might be higher than `employeeCountOcean` because of private profiles.", - "examples": [70] - }, - "revenue": { - "anyOf": [{ "$ref": "#/components/schemas/Revenue" }, { "type": "null" }], - "title": "Revenue range", - "description": "Revenue range", - "examples": ["1-10M"] - }, - "yearFounded": { - "anyOf": [{ "type": "integer" }, { "type": "null" }], - "title": "Yearfounded", - "description": "Year the company was founded", - "examples": [1999] - }, - "description": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Description", - "description": "Company's description", - "examples": [ - "Dunder Mifflin Paper Company, Inc. is a fictional paper and office supplies wholesale company featured in the American television series The Office." - ] - }, - "emails": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Emails", - "description": "Emails of the company", - "examples": [["email1@domain.com", "email2@domain.com"]] - }, - "phones": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/ContactNumber" }, "type": "array" }, - { "type": "null" } - ], - "title": "Phones", - "description": "Phones of the company", - "examples": [ - [ - { "country": "us", "number": "+1 212 456 7890", "primary": true }, - { "country": "ca", "number": "+1 250 555 0199" } - ] - ] - }, - "logo": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Logo", - "description": "Logo of the company (URL)", - "examples": [ - "https://cdn.ocean.io/companies-logos-v1/domain.com/020539e284d9318e805301b672ad23047c30818a.png" - ] - }, - "technologies": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Technologies", - "description": "Software technologies used by the company", - "examples": [["Accesso", "Adcash", "Atlassian Jira"]] - }, - "technologyCategories": { - "anyOf": [{ "items": { "type": "string" }, "type": "array" }, { "type": "null" }], - "title": "Technology categories", - "description": "Technology categories of the company", - "examples": [["Security", "Analytics", "Blogs"]] - }, - "mobileApps": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/MobileApp" }, "type": "array" }, - { "type": "null" } - ], - "title": "Mobile apps", - "description": "Mobile apps produced by the company" - }, - "webTraffic": { - "anyOf": [{ "$ref": "#/components/schemas/WebTraffic" }, { "type": "null" }], - "description": "Web traffic of the domain", - "examples": [ - { "bounceRate": 0.5227, "pageViews": 2155984, "pagesPerVisit": 4.88, "visits": 10000 } - ] - }, - "medias": { - "anyOf": [{ "$ref": "#/components/schemas/Medias" }, { "type": "null" }], - "title": "Social medias", - "description": "Social medias of the company" - }, - "name": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Name", - "description": "Name of the company", - "examples": ["Dunder Mifflin Paper Company"] - }, - "legalName": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Legalname", - "description": "Legal name of the company", - "examples": ["Dunder Mifflin Paper Company, Inc."] - }, - "locations": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/Location" }, "type": "array" }, - { "type": "null" } - ], - "title": "Locations", - "description": "Locations of the company" - }, - "departmentSizes": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/DepartmentSize" }, "type": "array" }, - { "type": "null" } - ], - "title": "Department sizes", - "description": "Number of employees per department", - "examples": [ - [ - { "department": "Accounting and Finance", "size": 10 }, - { "department": "Sales", "size": 15 } - ] - ] - }, - "rootUrl": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Rooturl", - "description": "Root url to access the website", - "examples": ["https://dundermifflinpaper.com/"] - }, - "faxes": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/ContactNumber" }, "type": "array" }, - { "type": "null" } - ], - "title": "Faxes", - "description": "Faxes of the company", - "examples": [[{ "country": "us", "number": "5709045026", "primary": true }]] - }, - "impressum": { - "anyOf": [{ "$ref": "#/components/schemas/Impressum" }, { "type": "null" }], - "title": "Impressum", - "description": "Impressum (Imprint) data of the company (only for Germany, Austria, Switzerland)" - } - }, - "type": "object", - "required": ["domain"], - "title": "PublicCompany" - }, - "PublicCompanySize": { - "type": "string", - "enum": [ - "0-1", - "2-10", - "11-50", - "51-200", - "201-500", - "501-1000", - "1001-5000", - "5001-10000", - "10001-50000", - "50001-100000", - "100001-500000", - "500000+" - ], - "title": "PublicCompanySize" - }, - "PublicCompanyWithScore": { - "properties": { - "company": { - "allOf": [{ "$ref": "#/components/schemas/PublicCompany" }], - "title": "Company", - "description": "Company found in the database" - }, - "score": { - "anyOf": [{ "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" }], - "title": "Similarity score", - "description": "Similarity score used for similarity search", - "examples": [0.96] - } - }, - "type": "object", - "required": ["company"], - "title": "PublicCompanyWithScore" - }, - "PublicCountryCodeToRegionMapping": { - "properties": { - "code": { - "type": "string", - "title": "Region code", - "description": "Region code", - "examples": ["AL"] - }, - "name": { - "type": "string", - "title": "Region name", - "description": "Region name", - "examples": ["Alabama"] - } - }, - "type": "object", - "title": "PublicCountryCodeToRegionMapping" - }, - "PublicGetDataFieldsResponse": { - "properties": { - "industries": { - "items": { "$ref": "#/components/schemas/PublicIndustries" }, - "type": "array", - "title": "Industries", - "description": "List of industries", - "examples": [ - [ - { - "industries": ["Advertising Platforms", "Biopharma"], - "industryCategory": "Administrative Services" - } - ] - ] - }, - "technologies": { - "items": { "$ref": "#/components/schemas/PublicTechnology" }, - "type": "array", - "title": "Technologies", - "description": "List of technologies", - "examples": [{ "categories": ["Chat"], "name": "ChatStack" }] - }, - "regions": { - "additionalProperties": { - "items": { "$ref": "#/components/schemas/PublicCountryCodeToRegionMapping" }, - "type": "array" - }, - "type": "object", - "title": "Country regions", - "description": "List of regions per country", - "examples": [{ "us": [{ "code": "AL", "name": "Alabama" }] }] - }, - "seniorities": { - "items": { "$ref": "#/components/schemas/Seniority" }, - "type": "array", - "title": "Seniorities", - "description": "List of seniorities computed from the job title of the person", - "examples": [["C-Level", "Manager"]] - }, - "departments": { - "items": { "$ref": "#/components/schemas/Department" }, - "type": "array", - "title": "Departments", - "description": "List of departments computed from the job title of the person", - "examples": [["Management", "Marketing and Advertising"]] - } - }, - "type": "object", - "title": "PublicGetDataFieldsResponse" - }, - "PublicIndustries": { - "properties": { - "industries": { - "items": { "type": "string" }, - "type": "array", - "title": "Industries", - "description": "List of industries", - "examples": [["Advertising Platforms", "Biopharma"]] - }, - "industryCategory": { - "type": "string", - "title": "Industry category", - "description": "Industry category name", - "examples": ["Administrative Services"] - } - }, - "type": "object", - "title": "PublicIndustries" - }, - "PublicPerson": { - "properties": { - "id": { - "type": "string", - "title": "Id", - "description": "Internal ocean id of the person", - "examples": ["e9447c74eafa8a19"] - }, - "domain": { - "type": "string", - "title": "Domain", - "description": "Domain of the company the person is working for", - "examples": ["google.com"] - }, - "name": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Name", - "description": "Full name of the person", - "examples": ["John Doe"] - }, - "firstName": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Firstname", - "description": "First name of the person", - "examples": ["John"] - }, - "lastName": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Lastname", - "description": "Last name of the person", - "examples": ["Doe"] - }, - "country": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Country", - "description": "Country code of the person", - "examples": ["us", "dk"] - }, - "location": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Location", - "description": "Location of the person", - "examples": ["Copenhagen, Capital Region, Denmark"] - }, - "linkedinUrl": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Linkedinurl", - "description": "Link to the linkedin profile of the person", - "examples": ["https://www.linkedin.com/in/someone"] - }, - "seniorities": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/Seniority" }, "type": "array" }, - { "type": "null" } - ], - "title": "Seniorities", - "description": "List of seniorities computed from the job title of the person", - "examples": [["C-Level", "Manager"]] - }, - "departments": { - "anyOf": [ - { "items": { "$ref": "#/components/schemas/Department" }, "type": "array" }, - { "type": "null" } - ], - "title": "Departments", - "description": "List of departments computed from the job title of the person", - "examples": [["Management", "Marketing and Advertising"]] - }, - "photo": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Photo", - "description": "Link to the person's profile picture on LinkedIn", - "examples": ["http://media.licdn.com/dms/image/somelink"] - }, - "jobTitle": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Jobtitle", - "description": "Job title of the person", - "examples": ["Professeur"] - }, - "jobTitleEnglish": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Jobtitleenglish", - "description": "English translation of the person's job title", - "examples": ["Teacher"] - }, - "summary": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Summary", - "description": "Summary of the person", - "examples": ["Some text that the person wrote to describe themselves"] - } - }, - "type": "object", - "required": ["id", "domain"], - "title": "PublicPerson" - }, - "PublicSearchCompaniesBody": { - "properties": { - "size": { - "type": "integer", - "maximum": 10000.0, - "minimum": 1.0, - "title": "Maximum number of results", - "description": "Number of companies to return. The maximum value is 10,000. To get more than 10,000 results, use `searchAfter`.", - "default": 50, - "examples": [10] - }, - "searchAfter": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Search after", - "description": "Use `searchAfter` returned by the previous request to get the next page", - "examples": ["NoBgdA7BAsBMEgGwBoAEAiADgGwK4HN8BTAJwC8wBjAewFt0BdIA"] - }, - "companiesFilters": { - "anyOf": [{ "$ref": "#/components/schemas/CompaniesFilters" }, { "type": "null" }], - "title": "Companies filters", - "description": "Collection of companies filters to be applied to the search" - }, - "peopleFilters": { - "anyOf": [{ "$ref": "#/components/schemas/PeopleFilters" }, { "type": "null" }], - "title": "People filters", - "description": "Collection of people filters to be applied to the search, the search results will display companies that have at least one person matching those filters" - } - }, - "additionalProperties": false, - "type": "object", - "required": ["companiesFilters"], - "title": "PublicSearchCompaniesBody" - }, - "PublicSearchCompaniesResult": { - "properties": { - "companies": { - "items": { "$ref": "#/components/schemas/PublicCompanyWithScore" }, - "type": "array", - "title": "Companies found", - "description": "Array of found companies. Returns empty array if no results" - }, - "searchAfter": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Search after", - "description": "Used for pagination. Use `searchAfter` returned by this request in the next request to get the next page of search results. If `searchAfter` is not present in the response then there is no next page.", - "examples": ["NoBgdA7BAsBMEgGwBoAEAiADgGwK4HN8BTAJwC8wBjAewFt0BdIA"] - }, - "detail": { - "type": "string", - "title": "Detail", - "description": "Status text", - "examples": ["OK"] - }, - "total": { - "anyOf": [{ "type": "integer" }, { "type": "null" }], - "title": "Total", - "description": "Total number of results of the search, accessible with pagination.", - "examples": [32871] - } - }, - "type": "object", - "required": ["companies", "detail"], - "title": "PublicSearchCompaniesResult" - }, - "PublicSearchPeopleBody": { - "properties": { - "size": { - "type": "integer", - "maximum": 10000.0, - "minimum": 1.0, - "title": "Maximum number of results", - "description": "Number of people to return. The maximum value is 10,000. To get more than 10,000 results, use `searchAfter`.", - "default": 50, - "examples": [10] - }, - "searchAfter": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Search after", - "description": "Use `searchAfter` returned by the previous request to get the next page", - "examples": ["NoBgdA7BAsBMEgGwBoAEAiADgGwK4HN8BTAJwC8wBjAewFt0BdIA"] - }, - "peopleFilters": { - "anyOf": [{ "$ref": "#/components/schemas/PeopleFilters" }, { "type": "null" }], - "title": "People filters", - "description": "Collection of filters to be applied to the search" - }, - "companiesFilters": { - "anyOf": [{ "$ref": "#/components/schemas/CompaniesFilters" }, { "type": "null" }], - "title": "Companies filters", - "description": "Collection of companies filters, the search results will display people that are associated with those companies" - }, - "onePersonPerDomain": { - "type": "boolean", - "title": "Onepersonperdomain", - "description": "Only return one person per company", - "default": false, - "examples": [true] - } - }, - "additionalProperties": false, - "type": "object", - "required": ["peopleFilters"], - "title": "PublicSearchPeopleBody" - }, - "PublicSearchPeopleResult": { - "properties": { - "people": { - "items": { "$ref": "#/components/schemas/PublicPerson" }, - "type": "array", - "title": "People" - }, - "searchAfter": { - "anyOf": [{ "type": "string" }, { "type": "null" }], - "title": "Search after", - "description": "Used for pagination. Use `searchAfter` returned by this request in the next request to get the next page of search results. If `searchAfter` is not present in the response then there is no next page.", - "examples": ["NoBgdA7BAsBMEgGwBoAEAiADgGwK4HN8BTAJwC8wBjAewFt0BdIA"] - }, - "detail": { - "type": "string", - "title": "Detail", - "description": "Status text", - "examples": ["OK"] - }, - "total": { - "anyOf": [{ "type": "integer" }, { "type": "null" }], - "title": "Total", - "description": "Total number of results of the search, accessible with pagination.", - "examples": [32871] - } - }, - "type": "object", - "required": ["people", "detail"], - "title": "PublicSearchPeopleResult" - }, - "PublicTechnology": { - "properties": { - "name": { - "type": "string", - "title": "Technology name", - "description": "The technology name", - "examples": ["ChatStack"] - }, - "categories": { - "items": { "type": "string" }, - "type": "array", - "title": "Technology categories", - "description": "Technology categories", - "examples": [["Chat"]] - } - }, - "type": "object", - "title": "PublicTechnology" - }, - "Revenue": { - "type": "string", - "enum": ["0-1M", "1-10M", "10-50M", "50-100M", "100-500M", "500-1000M", ">1000M"], - "title": "Revenue" - }, - "Seniority": { - "type": "string", - "enum": [ - "Owner", - "Founder", - "Board Member", - "C-Level", - "Partner", - "VP", - "Head", - "Director", - "Manager", - "Other" - ], - "title": "Seniority" - }, - "SocialMediasFilter": { - "properties": { - "medias": { - "items": { - "type": "string", - "enum": ["linkedin", "twitter", "facebook", "instagram", "youtube", "xing", "tiktok"] - }, - "type": "array", - "title": "Social medias", - "description": "Array of the social medias to include" - }, - "mode": { - "type": "string", - "enum": ["anyOf", "allOf"], - "title": "Search mode", - "description": "[default] anyOf - match at least one of the medias
allOf - match all of the medias", - "default": "anyOf" - } - }, - "additionalProperties": false, - "type": "object", - "required": ["medias"], - "title": "SocialMediasFilter" - }, - "State": { - "properties": { - "country": { - "type": "string", - "enum": ["at", "ca", "ch", "de", "es", "fr", "gb", "us"], - "title": "Country" - }, - "abbreviation": { - "type": "string", - "title": "State name abbreviation", - "description": "Valid ISO state abbreviation" - } - }, - "additionalProperties": false, - "type": "object", - "required": ["country", "abbreviation"], - "title": "State" - }, - "TechnologiesFilter": { - "properties": { - "technologies": { - "items": { "type": "string" }, - "type": "array", - "title": "Technologies", - "description": "Array of the technologies to include" - }, - "mode": { - "type": "string", - "enum": ["anyOf", "allOf"], - "title": "Search mode", - "description": "[default] anyOf - match at least one of the technologies
allOf - match all of the technologies", - "default": "anyOf" - } - }, - "additionalProperties": false, - "type": "object", - "required": ["technologies"], - "title": "TechnologiesFilter" - }, - "ValidationError": { - "properties": { - "loc": { - "items": { "anyOf": [{ "type": "string" }, { "type": "integer" }] }, - "type": "array", - "title": "Location" - }, - "msg": { "type": "string", "title": "Message" }, - "type": { "type": "string", "title": "Error Type" } - }, - "type": "object", - "required": ["loc", "msg", "type"], - "title": "ValidationError" - }, - "WebTraffic": { - "properties": { - "visits": { - "anyOf": [{ "type": "integer" }, { "type": "null" }], - "title": "Total visits for the last available month", - "description": "Total number of visits of the website for the last available month" - }, - "pageViews": { - "anyOf": [{ "type": "integer" }, { "type": "null" }], - "title": "Website views", - "description": "Number of views of the website for the last available month" - }, - "pagesPerVisit": { - "anyOf": [{ "type": "number" }, { "type": "null" }], - "title": "Pages per visit", - "description": "Average number of pages viewed per visit for the last available month" - }, - "bounceRate": { - "anyOf": [{ "type": "number" }, { "type": "null" }], - "title": "Bouncerate", - "description": "Bounce rate of the domain for the last available month" - } - }, - "type": "object", - "title": "WebTraffic" - } - }, - "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } - }, - "x-topics": [ - { - "id": "authentication", - "title": "Authentication", - "content": "\n Authentication for accessing the API is handled through API tokens, which can be generated and managed within the [user's account settings](https://app.ocean.io/settings/api-tokens).\n API tokens provide a secure way to authenticate API requests and ensure that only authorized users can access the API resources.\n Users must include their API token in every API request either as a header parameter named \"X-Api-Token\" or as a query parameter named \"apiToken\".\n The API token serves as a unique identifier for the organization's account and grants access to the specified API endpoints based on the user's permissions.\n ", - "example": "```\ncurl -X POST 'https://api.ocean.io/v1/endpoint?apiToken=YOUR_API_TOKEN_HERE' -d '{\n \"name\": \"New Data\",\n \"description\": \"This is a new data entry.\"\n }'\n ```" - }, - { - "id": "pagination", - "title": "Pagination", - "content": "\n Pagination is employed to manage large datasets returned by API endpoints, ensuring efficient retrieval and navigation of results.\n In this API, pagination is facilitated using the \"searchAfter\" parameter, which serves as a pointer to the next set of results.\n After making an initial request, the API response includes this \"searchAfter\" value, which corresponds to the last item from the current page of results.\n To retrieve the subsequent page of results, users include this \"searchAfter\" value in the subsequent API request as a parameter.\n The API then returns the next page of results, starting from the item immediately after the one indicated by the provided \"searchAfter\" value.\n This mechanism enables users to iteratively retrieve paginated data without duplication or omission, allowing for efficient navigation through large datasets.\n Additionally, users can control the size of each page of results by specifying the desired number of items per page in their API requests.\n Note that there is a maximum limit on the number of items per page, which is specified in the API documentation for each endpoint.\n " - }, - { - "id": "errors", - "title": "Errors", - "content": "\n Ocean.io adopts standard HTTP error codes to convey various issues encountered during API interactions.\n \n> In general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the `5xx` range indicate an error with our servers.\n " - }, - { - "id": "rate-limiting", - "title": "Rate limiting", - "content": "\n Rate limits are in place to ensure fair usage of the API resources and maintain system stability. By default, the rate limit is set to 60 requests per minute for most endpoints.\n However, some specific endpoints may have different rate limits tailored to their respective functionalities.\n Users can be informed about the specific rate limit for each endpoint through the API documentation or other provided resources.\n Exceeding the rate limit for any given endpoint will result in subsequent requests being throttled until the rate limit window resets. Adhering to the specified rate limits is essential to prevent disruptions to service and ensure optimal performance for all users.\n If you require a higher rate limit, please contact us.\n

The API returns the following headers when a rate limit is exceeded:\n - `Retry-After`: The number of seconds to wait before making another request.\n - `X-RateLimit-Limit`: The maximum number of requests allowed in the current rate limit window.\n " - } - ], - "x-introduction-pages": [ - { - "id": "authentication", - "title": "Authentication", - "content": "\n Authentication for accessing the API is handled through API tokens, which can be generated and managed within the [user's account settings](https://app.ocean.io/settings/api-tokens).\n API tokens provide a secure way to authenticate API requests and ensure that only authorized users can access the API resources.\n Users must include their API token in every API request either as a header parameter named \"X-Api-Token\" or as a query parameter named \"apiToken\".\n The API token serves as a unique identifier for the organization's account and grants access to the specified API endpoints based on the user's permissions.\n ", - "example": "```bash\ncurl -X POST 'https://api.ocean.io/v1/endpoint?apiToken=YOUR_API_TOKEN_HERE' -d '{\n \"name\": \"New Data\",\n \"description\": \"This is a new data entry.\"\n}\n```" - }, - { - "id": "pagination", - "title": "Pagination", - "content": "\n Pagination is employed to manage large datasets returned by API endpoints, ensuring efficient retrieval and navigation of results.\n In this API, pagination is facilitated using the \"searchAfter\" parameter, which serves as a pointer to the next set of results.\n After making an initial request, the API response includes this \"searchAfter\" value, which corresponds to the last item from the current page of results.\n To retrieve the subsequent page of results, users include this \"searchAfter\" value in the subsequent API request as a parameter.\n The API then returns the next page of results, starting from the item immediately after the one indicated by the provided \"searchAfter\" value.\n This mechanism enables users to iteratively retrieve paginated data without duplication or omission, allowing for efficient navigation through large datasets.\n Additionally, users can control the size of each page of results by specifying the desired number of items per page in their API requests.\n Note that there is a maximum limit on the number of items per page, which is specified in the API documentation for each endpoint.\n " - }, - { - "id": "errors", - "title": "Errors", - "content": "\n Ocean.io adopts standard HTTP error codes to convey various issues encountered during API interactions.\n \n> In general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the `5xx` range indicate an error with our servers.\n ", - "example": "\n | Status Code | Error Name | Description |\n|------------------------|----------------------|-------------------------------------------------------------------------------------------------|\n| **200** | OK | Everything worked as expected. |\n| **400** | Bad Request | The request was unacceptable, often due to missing a required parameter. |\n| **401** | Unauthorized | No valid API key provided. |\n| **403** | Forbidden | The API key doesn't have permissions to perform the request. |\n| **404** | Not Found | The requested resource doesn't exist. |\n| **429** | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.|\n| **500, 502, 503, 504** | Server Errors | Something went wrong on Ocean.s end. |\n " - }, - { - "id": "rate-limiting", - "title": "Rate limiting", - "content": "\n Rate limits are in place to ensure fair usage of the API resources and maintain system stability. By default, the rate limit is set to 60 requests per minute for most endpoints.\n However, some specific endpoints may have different rate limits tailored to their respective functionalities.\n Users can be informed about the specific rate limit for each endpoint through the API documentation or other provided resources.\n Exceeding the rate limit for any given endpoint will result in subsequent requests being throttled until the rate limit window resets. Adhering to the specified rate limits is essential to prevent disruptions to service and ensure optimal performance for all users.\n If you require a higher rate limit, please contact us.\n
The API returns the following headers when a rate limit is exceeded:\n\n- *Retry-After*: The number of seconds to wait before making another request.\n\n- *X-RateLimit-Limit*: The maximum number of requests allowed in the current rate limit window.\n " - } - ] -} diff --git a/src/petstore-v3.1.json b/src/petstore-v3.1.json deleted file mode 100644 index a8020f0..0000000 --- a/src/petstore-v3.1.json +++ /dev/null @@ -1,178 +0,0 @@ -{ - "openapi": "3.1.0", - "info": { - "version": "1.0.0", - "title": "Swagger Petstore", - "license": { - "name": "MIT", - "url": "https://opensource.org/licenses/MIT" - } - }, - "servers": [ - { - "url": "http://petstore.swagger.io/v1" - } - ], - "paths": { - "/pets": { - "get": { - "summary": "List all pets", - "operationId": "listPets", - "tags": [ - "pets" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "How many items to return at one time (max 100)", - "required": false, - "schema": { - "type": "integer", - "format": "int32" - } - } - ], - "responses": { - "200": { - "description": "A paged array of pets", - "headers": { - "x-next": { - "description": "A link to the next page of responses", - "schema": { - "type": "string" - } - } - }, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Pets" - } - } - } - }, - "default": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - }, - "post": { - "summary": "Create a pet", - "operationId": "createPets", - "tags": [ - "pets" - ], - "responses": { - "201": { - "description": "Null response" - }, - "default": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/pets/{petId}": { - "get": { - "summary": "Info for a specific pet", - "operationId": "showPetById", - "tags": [ - "pets" - ], - "parameters": [ - { - "name": "petId", - "in": "path", - "required": true, - "description": "The id of the pet to retrieve", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "Expected response to a valid request", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Pet" - } - } - } - }, - "default": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - } - }, - "components": { - "schemas": { - "Pet": { - "type": "object", - "required": [ - "id", - "name" - ], - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "Pets": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Pet" - } - }, - "Error": { - "type": "object", - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } - } -} \ No newline at end of file diff --git a/src/sendgrid.json b/src/sendgrid.json deleted file mode 100644 index 6c2ee82..0000000 --- a/src/sendgrid.json +++ /dev/null @@ -1,46080 +0,0 @@ -{ - "openapi": "3.1.0", - "info": { - "version": "", - "title": "Email Activity (beta)", - "description": "The Beta endpoints for the new Email Activity APIs - functionality is subject to change without notice. You may not have access to this Beta endpoint.\n\nEmail Activity offers filtering and search by event type for two days worth of data. There is an optional add-on to store 60 days worth of data. This add-on also gives you access to the ability to download a CSV of the 60 days worth of email event data. The Beta endpoints for the new Email Activity APIs - functionality is subject to change without notice. You may not have access to this Beta endpoint.\n\nEmail Activity offers filtering and search by event type for two days worth of data. There is an optional add-on to store 60 days worth of data. This add-on also gives you access to the ability to download a CSV of the 60 days worth of email event data." - }, - "tags": [ - { - "name": "Subuser Monitor Settings" - }, - { - "name": "segmenting contacts" - }, - { - "name": "Single Sign-On Settings" - }, - { - "name": "Settings - Partner" - }, - { - "name": "Contacts API - Recipients" - }, - { - "name": "Settings - Inbound Parse" - }, - { - "name": "Segmenting Contacts" - }, - { - "name": "IP Access Management" - }, - { - "name": "Messages" - }, - { - "name": "Suppressions - Unsubscribe Groups" - }, - { - "name": "Email CNAME records" - }, - { - "name": "CSV (UI only)" - }, - { - "name": "Bounces API" - }, - { - "name": "Designs API" - }, - { - "name": "Custom Fields" - }, - { - "name": "Segmenting Contacts V2 - Beta" - }, - { - "name": "Subuser Statistics" - }, - { - "name": "Send Test Email" - }, - { - "name": "IP Addresses" - }, - { - "name": "Query" - }, - { - "name": "V3" - }, - { - "name": "Invalid Emails API" - }, - { - "name": "Webhooks" - }, - { - "name": "Suppressions - Global Suppressions" - }, - { - "name": "Settings - Tracking" - }, - { - "name": "Contacts API - Lists" - }, - { - "name": "Marketing Campaigns Stats" - }, - { - "name": "API Key Permissions" - }, - { - "name": "Domain Authentication" - }, - { - "name": "Sender Identities API" - }, - { - "name": "Single Sign-On Teammates" - }, - { - "name": "Mail Send" - }, - { - "name": "Settings - Enforced TLS" - }, - { - "name": "IP Warmup" - }, - { - "name": "Categories" - }, - { - "name": "Campaigns API" - }, - { - "name": "Teammates" - }, - { - "name": "Sender Verification" - }, - { - "name": "Single Sends" - }, - { - "name": "Blocks API" - }, - { - "name": "Contacts" - }, - { - "name": "Certificates" - }, - { - "name": "Contacts API - Segments" - }, - { - "name": "Senders" - }, - { - "name": "Contacts API - Custom Fields" - }, - { - "name": "Spam Reports API" - }, - { - "name": "Subusers API" - }, - { - "name": "Link branding" - }, - { - "name": "Suppressions - Suppressions" - }, - { - "name": "Users API" - }, - { - "name": "Settings - Mail" - }, - { - "name": "API Keys" - }, - { - "name": "Transactional Templates" - }, - { - "name": "Reverse DNS" - }, - { - "name": "Email Address Validation" - }, - { - "name": "Transactional Templates Versions" - }, - { - "name": "Lists" - }, - { - "name": "Cancel Scheduled Sends" - }, - { - "name": "Stats" - }, - { - "name": "Alerts" - }, - { - "name": "IP Pools" - } - ], - "paths": { - "/mail/send": { - "post": { - "operationId": "POST_mail-send", - "summary": "v3 Mail Send", - "tags": ["Mail Send"], - "description": "The Mail Send endpoint allows you to send email over SendGrid’s v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, see our [v2 API Reference](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n## Helper Libraries\n\nTwilio SendGrid provides libraries to help you quickly and easily integrate with the v3 Web API in 7 different languages:\n\n* [C#](https://github.com/sendgrid/sendgrid-csharp) \n* [Go](https://github.com/sendgrid/sendgrid-go)\n* [Java](https://github.com/sendgrid/sendgrid-java)\n* [Node JS](https://github.com/sendgrid/sendgrid-nodejs)\n* [PHP](https://github.com/sendgrid/sendgrid-php)\n* [Python](https://github.com/sendgrid/sendgrid-python)\n* [Ruby](https://github.com/sendgrid/sendgrid-ruby)\n\n## Dynamic Transactional Templates and Handlebars\n\nIn order to send a dynamic template, specify the template ID with the `template_id` parameter. \n\nTo specify handlebar substitutions, define your substitutions in the request JSON with this syntax:\n\n```\n\"dynamic_template_data\": {\n      \"guest\": \"Jane Doe\",\n      \"partysize\": \"4\",\n      \"english\": true,\n      \"date\": \"April 1st, 2021\"\n    }\n```\n\nFor more information about Dynamic Transactional Templates and Handlebars, see our documentation and reference pages.\n\n* [How to send an email with Dynamic Transactional Templates\n](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/)\n* [Using Handlebars](https://sendgrid.com/docs/for-developers/sending-email/using-handlebars/) \n\n## Mail Body Compression\n\nMail body compression is available to some high volume accounts. Talk to your CSM if you are interested in this functionality. Mail body compression works by setting up a JSON payload as defined on this page, then compressing it with gzip (the gzip file can be no more than 30mb).\n\nTo use mail body compression:\n\n1. Add a `Content-Encoding` header, with a value of `gzip`. \n a. `Content-Encoding: gzip` \n2. Send the gzip as a data-binary. \n a. `--data-binary '@data.json.gz'\n`\n\n## Multiple Reply-To Emails\n\nUsing `reply_to_list` allows senders to include more than one recipient email address to receive reply and/or bounce messages from the recipient of the email.\n\n### Usage Considerations\n\n* `reply_to` is mutually exclusive with `reply_to_list`. If both are used, then the API call will be rejected. \n* The `reply_to_list` object, when used, must at least have an email parameter and may also contain a name parameter.\n* Each email address in the `reply_to_list` should be unique.\n* There is a limit of 1000 `reply_to_list` emails per mail/send request.\n* In SMTP calls, we will omit any invalid emails.\n\n### Possible 400 Error Messages\n\n* `reply_to` is mutually exclusive with `reply_to_list`.\n* The `reply_to_list` object, when used, must at least have an email parameter and may also contain a name parameter.\n* Each email address in the `reply_to_list` should be unique.\n* There is a limit of X `reply_to` emails per mail/send request.\n* The `reply_to_list` email does not contain a valid address.\n* The `reply_to_list` email exceeds the maximum total length of X characters.\n* The `reply_to_list` email parameter is required.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "personalizations": { - "type": "array", - "description": "An array of messages and their metadata. Each object within personalizations can be thought of as an envelope - it defines who should receive an individual message and how that message should be handled. See our [Personalizations documentation](https://sendgrid.com/docs/for-developers/sending-email/personalizations/) for examples.", - "uniqueItems": false, - "maxItems": 1000, - "items": { - "type": "object", - "properties": { - "from": { - "$ref": "#/components/schemas/from_email_object" - }, - "to": { - "$ref": "#/components/schemas/to_email_array" - }, - "cc": { - "type": "array", - "description": "An array of recipients who will receive a copy of your email. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name.", - "maxItems": 1000, - "items": { - "$ref": "#/components/schemas/cc_bcc_email_object" - } - }, - "bcc": { - "type": "array", - "description": "An array of recipients who will receive a blind carbon copy of your email. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name.", - "maxItems": 1000, - "items": { - "$ref": "#/components/schemas/cc_bcc_email_object" - } - }, - "subject": { - "type": "string", - "description": "The subject of your email. See character length requirements according to [RFC 2822](http://stackoverflow.com/questions/1592291/what-is-the-email-subject-length-limit#answer-1592310).", - "minLength": 1 - }, - "headers": { - "type": "object", - "description": "A collection of JSON key/value pairs allowing you to specify handling instructions for your email. You may not overwrite the following headers: `x-sg-id`, `x-sg-eid`, `received`, `dkim-signature`, `Content-Type`, `Content-Transfer-Encoding`, `To`, `From`, `Subject`, `Reply-To`, `CC`, `BCC`" - }, - "substitutions": { - "type": "object", - "description": "Substitutions allow you to insert data without using Dynamic Transactional Templates. This field should **not** be used in combination with a Dynamic Transactional Template, which can be identified by a `template_id` starting with `d-`. This field is a collection of key/value pairs following the pattern \"substitution_tag\":\"value to substitute\". The key/value pairs must be strings. These substitutions will apply to the text and html content of the body of your email, in addition to the `subject` and `reply-to` parameters. The total collective size of your substitutions may not exceed 10,000 bytes per personalization object.", - "maxProperties": 10000 - }, - "dynamic_template_data": { - "type": "object", - "description": "Dynamic template data is available using Handlebars syntax in Dynamic Transactional Templates. This field should be used in combination with a Dynamic Transactional Template, which can be identified by a `template_id` starting with `d-`. This field is a collection of key/value pairs following the pattern \"variable_name\":\"value to insert\"." - }, - "custom_args": { - "type": "object", - "description": "Values that are specific to this personalization that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. This field may not exceed 10,000 bytes.", - "maxProperties": 10000 - }, - "send_at": { - "type": "integer", - "description": "A unix timestamp allowing you to specify when your email should be delivered. Scheduling delivery more than 72 hours in advance is forbidden." - } - }, - "required": ["to"] - } - }, - "from": { - "$ref": "#/components/schemas/from_email_object" - }, - "reply_to": { - "$ref": "#/components/schemas/reply_to_email_object" - }, - "reply_to_list": { - "type": "array", - "description": "An array of recipients who will receive replies and/or bounces. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name. You can either choose to use “reply_to” field or “reply_to_list” but not both.", - "uniqueItems": true, - "maxItems": 1000, - "items": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address where any replies or bounces will be returned.", - "format": "email" - }, - "name": { - "type": "string", - "description": "A name or title associated with the `reply_to_list` email address." - } - }, - "required": ["email"] - } - }, - "subject": { - "type": "string", - "description": "The global or 'message level' subject of your email. This may be overridden by subject lines set in personalizations.", - "minLength": 1 - }, - "content": { - "type": "array", - "description": "An array where you can specify the content of your email. You can include multiple [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of content, but you must specify at least one MIME type. To include more than one MIME type, add another object to the array containing the `type` and `value` parameters.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The MIME type of the content you are including in your email (e.g., `“text/plain”` or `“text/html”`).", - "minLength": 1 - }, - "value": { - "type": "string", - "description": "The actual content of the specified MIME type that you are including in your email.", - "minLength": 1 - } - }, - "required": ["type", "value"] - } - }, - "attachments": { - "type": "array", - "description": "An array of objects where you can specify any attachments you want to include.", - "items": { - "type": "object", - "properties": { - "content": { - "type": "string", - "description": "The Base64 encoded content of the attachment.", - "minLength": 1 - }, - "type": { - "type": "string", - "description": "The MIME type of the content you are attaching (e.g., `“text/plain”` or `“text/html”`).", - "minLength": 1 - }, - "filename": { - "type": "string", - "description": "The attachment's filename." - }, - "disposition": { - "type": "string", - "default": "attachment", - "description": "The attachment's content-disposition, specifying how you would like the attachment to be displayed. For example, `“inline”` results in the attached file are displayed automatically within the message while `“attachment”` results in the attached file require some action to be taken before it is displayed, such as opening or downloading the file.", - "enum": ["inline", "attachment"] - }, - "content_id": { - "type": "string", - "description": "The attachment's content ID. This is used when the disposition is set to `“inline”` and the attachment is an image, allowing the file to be displayed within the body of your email." - } - }, - "required": ["content", "filename"] - } - }, - "template_id": { - "type": "string", - "description": "An email template ID. A template that contains a subject and content — either text or html — will override any subject and content values specified at the personalizations or message level." - }, - "headers": { - "description": "An object containing key/value pairs of header names and the value to substitute for them. The key/value pairs must be strings. You must ensure these are properly encoded if they contain unicode characters. These headers cannot be one of the reserved headers.", - "type": "object" - }, - "categories": { - "type": "array", - "description": "An array of category names for this message. Each category name may not exceed 255 characters. ", - "uniqueItems": true, - "maxItems": 10, - "items": { - "type": "string", - "maxLength": 255 - } - }, - "custom_args": { - "description": "Values that are specific to the entire send that will be carried along with the email and its activity data. Key/value pairs must be strings. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. This parameter is overridden by `custom_args` set at the personalizations level. Total `custom_args` size may not exceed 10,000 bytes.", - "type": "string" - }, - "send_at": { - "type": "integer", - "description": "A unix timestamp allowing you to specify when you want your email to be delivered. This may be overridden by the `send_at` parameter set at the personalizations level. Delivery cannot be scheduled more than 72 hours in advance. If you have the flexibility, it's better to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour. Scheduling email to avoid peak times — for example, scheduling at 10:53 — can result in lower deferral rates due to the reduced traffic during off-peak times." - }, - "batch_id": { - "type": "string", - "description": "An ID representing a batch of emails to be sent at the same time. Including a `batch_id` in your request allows you include this email in that batch. It also enables you to cancel or pause the delivery of that batch. For more information, see the [Cancel Scheduled Sends API](https://sendgrid.com/docs/api-reference/)." - }, - "asm": { - "type": "object", - "description": "An object allowing you to specify how to handle unsubscribes.", - "properties": { - "group_id": { - "type": "integer", - "description": "The unsubscribe group to associate with this email." - }, - "groups_to_display": { - "type": "array", - "description": "An array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page.", - "maxItems": 25, - "items": { - "type": "integer" - } - } - }, - "required": ["group_id"] - }, - "ip_pool_name": { - "type": "string", - "description": "The IP Pool that you would like to send this email from.", - "minLength": 2, - "maxLength": 64 - }, - "mail_settings": { - "type": "object", - "description": "A collection of different mail settings that you can use to specify how you would like this email to be handled.", - "properties": { - "bypass_list_management": { - "type": "object", - "description": "Allows you to bypass all unsubscribe groups and suppressions to ensure that the email is delivered to every single recipient. This should only be used in emergencies when it is absolutely necessary that every recipient receives your email. This filter cannot be combined with any other bypass filters. See our [documentation](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) for more about bypass filters.", - "properties": { - "enable": { - "type": "boolean", - "description": "Indicates if this setting is enabled." - } - } - }, - "bypass_spam_management": { - "type": "object", - "description": "Allows you to bypass the spam report list to ensure that the email is delivered to recipients. Bounce and unsubscribe lists will still be checked; addresses on these other lists will not receive the message. This filter cannot be combined with the `bypass_list_management` filter. See our [documentation](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) for more about bypass filters.", - "properties": { - "enable": { - "type": "boolean", - "description": "Indicates if this setting is enabled." - } - } - }, - "bypass_bounce_management": { - "type": "object", - "description": "Allows you to bypass the bounce list to ensure that the email is delivered to recipients. Spam report and unsubscribe lists will still be checked; addresses on these other lists will not receive the message. This filter cannot be combined with the `bypass_list_management` filter. See our [documentation](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) for more about bypass filters.", - "properties": { - "enable": { - "type": "boolean", - "description": "Indicates if this setting is enabled." - } - } - }, - "bypass_unsubscribe_management": { - "type": "object", - "description": "Allows you to bypass the global unsubscribe list to ensure that the email is delivered to recipients. Bounce and spam report lists will still be checked; addresses on these other lists will not receive the message. This filter applies only to global unsubscribes and will not bypass group unsubscribes. This filter cannot be combined with the `bypass_list_management` filter. See our [documentation](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) for more about bypass filters.", - "properties": { - "enable": { - "type": "boolean", - "description": "Indicates if this setting is enabled." - } - } - }, - "footer": { - "type": "object", - "description": "The default footer that you would like included on every email.", - "properties": { - "enable": { - "type": "boolean", - "description": "Indicates if this setting is enabled." - }, - "text": { - "type": "string", - "description": "The plain text content of your footer." - }, - "html": { - "type": "string", - "description": "The HTML content of your footer." - } - } - }, - "sandbox_mode": { - "type": "object", - "description": "Sandbox Mode allows you to send a test email to ensure that your request body is valid and formatted correctly.", - "properties": { - "enable": { - "type": "boolean", - "description": "Indicates if this setting is enabled." - } - } - } - } - }, - "tracking_settings": { - "type": "object", - "description": "Settings to determine how you would like to track the metrics of how your recipients interact with your email.", - "properties": { - "click_tracking": { - "type": "object", - "description": "Allows you to track if a recipient clicked a link in your email.", - "properties": { - "enable": { - "type": "boolean", - "description": "Indicates if this setting is enabled." - }, - "enable_text": { - "type": "boolean", - "description": "Indicates if this setting should be included in the `text/plain` portion of your email." - } - } - }, - "open_tracking": { - "type": "object", - "description": "Allows you to track if the email was opened by including a single pixel image in the body of the content. When the pixel is loaded, Twilio SendGrid can log that the email was opened.", - "properties": { - "enable": { - "type": "boolean", - "description": "Indicates if this setting is enabled." - }, - "substitution_tag": { - "type": "string", - "description": "Allows you to specify a substitution tag that you can insert in the body of your email at a location that you desire. This tag will be replaced by the open tracking pixel." - } - } - }, - "subscription_tracking": { - "type": "object", - "description": "Allows you to insert a subscription management link at the bottom of the text and HTML bodies of your email. If you would like to specify the location of the link within your email, you may use the `substitution_tag`.", - "properties": { - "enable": { - "type": "boolean", - "description": "Indicates if this setting is enabled." - }, - "text": { - "type": "string", - "description": "Text to be appended to the email with the subscription tracking link. You may control where the link is by using the tag <% %>" - }, - "html": { - "type": "string", - "description": "HTML to be appended to the email with the subscription tracking link. You may control where the link is by using the tag <% %>" - }, - "substitution_tag": { - "type": "string", - "description": "A tag that will be replaced with the unsubscribe URL. for example: `[unsubscribe_url]`. If this parameter is used, it will override both the `text` and `html` parameters. The URL of the link will be placed at the substitution tag’s location with no additional formatting." - } - } - }, - "ganalytics": { - "type": "object", - "description": "Allows you to enable tracking provided by Google Analytics.", - "properties": { - "enable": { - "type": "boolean", - "description": "Indicates if this setting is enabled." - }, - "utm_source": { - "type": "string", - "description": "Name of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email)" - }, - "utm_medium": { - "type": "string", - "description": "Name of the marketing medium. (e.g. Email)" - }, - "utm_term": { - "type": "string", - "description": "Used to identify any paid keywords." - }, - "utm_content": { - "type": "string", - "description": "Used to differentiate your campaign from advertisements." - }, - "utm_campaign": { - "type": "string", - "description": "The name of the campaign." - } - } - } - } - } - }, - "required": ["personalizations", "from", "subject", "content"], - "example": { - "personalizations": [ - { - "to": [ - { - "email": "john_doe@example.com", - "name": "John Doe" - }, - { - "email": "julia_doe@example.com", - "name": "Julia Doe" - } - ], - "cc": [ - { - "email": "jane_doe@example.com", - "name": "Jane Doe" - } - ], - "bcc": [ - { - "email": "james_doe@example.com", - "name": "Jim Doe" - } - ] - }, - { - "from": { - "email": "sales@example.com", - "name": "Example Sales Team" - }, - "to": [ - { - "email": "janice_doe@example.com", - "name": "Janice Doe" - } - ], - "bcc": [ - { - "email": "jordan_doe@example.com", - "name": "Jordan Doe" - } - ] - } - ], - "from": { - "email": "orders@example.com", - "name": "Example Order Confirmation" - }, - "reply_to": { - "email": "customer_service@example.com", - "name": "Example Customer Service Team" - }, - "subject": "Your Example Order Confirmation", - "content": [ - { - "type": "text/html", - "value": "

Hello from Twilio SendGrid!

Sending with the email service trusted by developers and marketers for time-savings, scalability, and delivery expertise.

%open-track%

" - } - ], - "attachments": [ - { - "content": "PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg==", - "filename": "index.html", - "type": "text/html", - "disposition": "attachment" - } - ], - "categories": ["cake", "pie", "baking"], - "send_at": 1617260400, - "batch_id": "AsdFgHjklQweRTYuIopzXcVBNm0aSDfGHjklmZcVbNMqWert1znmOP2asDFjkl", - "asm": { - "group_id": 12345, - "groups_to_display": [12345] - }, - "ip_pool_name": "transactional email", - "mail_settings": { - "bypass_list_management": { - "enable": false - }, - "footer": { - "enable": false - }, - "sandbox_mode": { - "enable": false - } - }, - "tracking_settings": { - "click_tracking": { - "enable": true, - "enable_text": false - }, - "open_tracking": { - "enable": true, - "substitution_tag": "%open-track%" - }, - "subscription_tracking": { - "enable": false - } - } - } - } - } - } - }, - "responses": { - "202": { - "description": "" - }, - "400": { - "$ref": "#/components/responses/trait_mailSendErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "413": { - "$ref": "#/components/responses/trait_mailSendErrors_413" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_mail-send", - "public": true, - "mock": { - "dynamic": false, - "statusCode": 200, - "enabled": false - } - } - } - }, - "/mail/batch": { - "post": { - "operationId": "POST_mail-batch", - "summary": "Create a batch ID", - "tags": ["Cancel Scheduled Sends"], - "description": "**This endpoint allows you to generate a new batch ID.**\n\nOnce a `batch_id` is created, you can associate it with a scheduled send using the `/mail/send` endpoint. Passing the `batch_id` as a field in the `/mail/send` request body will assign the ID to the send you are creating.\n\nOnce an ID is associated with a scheduled send, the send can be accessed and its send status can be modified using the `batch_id`.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_batch_id" - }, - "examples": { - "response": { - "value": { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_cancelScheduledSendsErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_mail-batch", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/user/scheduled_sends": { - "post": { - "operationId": "POST_user-scheduled_sends", - "summary": "Cancel or pause a scheduled send", - "tags": ["Cancel Scheduled Sends"], - "description": "**This endpoint allows you to cancel or pause a scheduled send associated with a `batch_id`.**\n\nPassing this endpoint a `batch_id` and status will cancel or pause the scheduled send.\n\nOnce a scheduled send is set to `pause` or `cancel` you must use the \"Update a scheduled send\" endpoint to change its status or the \"Delete a cancellation or pause from a scheduled send\" endpoint to remove the status. Passing a status change to a scheduled send that has already been paused or cancelled will result in a `400` level status code.\n\nIf the maximum number of cancellations/pauses are added to a send, a `400` level status code will be returned.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "title": "Cancel or pause a scheduled send request", - "type": "object", - "properties": { - "batch_id": { - "type": "string", - "description": "The batch ID is the identifier that your scheduled mail sends share.", - "pattern": "^[a-zA-Z0-9]" - }, - "status": { - "type": "string", - "default": "pause", - "description": "The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id}", - "enum": ["pause", "cancel"] - } - }, - "required": ["batch_id", "status"], - "example": { - "batch_id": "YOUR_BATCH_ID", - "status": "pause" - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/user_scheduled_send_status" - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_cancelScheduledSendsErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_user-scheduledsends", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_user-scheduled_sends", - "summary": "Retrieve all scheduled sends", - "tags": ["Cancel Scheduled Sends"], - "description": "**This endpoint allows you to retrieve all cancelled and paused scheduled send information.**\n\nThis endpoint will return only the scheduled sends that are associated with a `batch_id`. If you have scheduled a send using the `/mail/send` endpoint and the `send_at` field but no `batch_id`, the send will be scheduled for delivery; however, it will not be returned by this endpoint. For this reason, you should assign a `batch_id` to any scheduled send you may need to pause or cancel in the future.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/user_scheduled_send_status" - } - }, - "examples": { - "response": { - "value": [ - { - "batch_id": "QzZmYzLTVWIwYgYzJlM2NhNWI", - "status": "cancel" - }, - { - "batch_id": "mQzZmYzLTVlM2NhNWIwYgYzJl", - "status": "cancel" - } - ] - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_cancelScheduledSendsErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-scheduledsends", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 200 - } - } - } - }, - "/mail/batch/{batch_id}": { - "parameters": [ - { - "name": "batch_id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_mail-batch-batch_id", - "summary": "Validate batch ID", - "tags": ["Cancel Scheduled Sends"], - "description": "**This endpoint allows you to validate a batch ID.**\n\nWhen you pass a valid `batch_id` to this endpoint, it will return a `200` status code and the batch ID itself.\n\nIf you pass an invalid `batch_id` to the endpoint, you will receive a `400` level status code and an error message.\n\nA `batch_id` does not need to be assigned to a scheduled send to be considered valid. A successful response means only that the `batch_id` has been created, but it does not indicate that it has been associated with a send.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_batch_id" - }, - "examples": { - "response": { - "value": { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_cancelScheduledSendsErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mail-batch-batchid", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/user/scheduled_sends/{batch_id}": { - "parameters": [ - { - "name": "batch_id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_user-scheduled_sends-batch_id", - "summary": "Retrieve scheduled send", - "tags": ["Cancel Scheduled Sends"], - "description": "**This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "title": "Retrieve scheduled send response", - "items": { - "$ref": "#/components/schemas/user_scheduled_send_status" - } - }, - "examples": { - "response": { - "value": [ - { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", - "status": "cancel" - }, - { - "batch_id": "IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg", - "status": "pause" - } - ] - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_cancelScheduledSendsErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-scheduledsends-batchid", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_user-scheduled_sends-batch_id", - "summary": "Update a scheduled send", - "tags": ["Cancel Scheduled Sends"], - "description": "**This endpoint allows you to update the status of a scheduled send for the given `batch_id`.**\n\nIf you have already set a `cancel` or `pause` status on a scheduled send using the \"Cancel or pause a scheduled send\" endpoint, you can update it's status using this endpoint. Attempting to update a status once it has been set with the \"Cancel or pause a scheduled send\" endpoint will result in a `400` error.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "status": { - "type": "string", - "description": "The status you would like the scheduled send to have.", - "enum": ["cancel", "pause"] - } - }, - "required": ["status"], - "example": { - "status": "pause" - } - } - } - } - }, - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "nullable": true - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_cancelScheduledSendsErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_user-scheduledsends-batchid", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_user-scheduled_sends-batch_id", - "summary": "Delete a cancellation or pause from a scheduled send", - "tags": ["Cancel Scheduled Sends"], - "description": "**This endpoint allows you to delete the cancellation/pause of a scheduled send.**\n\nScheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "" - }, - "400": { - "$ref": "#/components/responses/trait_cancelScheduledSendsErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_user-scheduledsends-batchid", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/api_keys": { - "post": { - "operationId": "create-api-keys", - "summary": "Create API keys", - "tags": ["API Keys"], - "description": "**This endpoint allows you to create a new API Key for the user.**\n\nTo create your initial SendGrid API Key, you should [use the SendGrid App](https://app.sendgrid.com/settings/api_keys). Once you have created a first key with scopes to manage additional API keys, you can use this API for all other key management.\n\n> There is a limit of 100 API Keys on your account.\n\nA JSON request body containing a `name` property is required when making requests to this endpoint. If the number of maximum keys, 100, is reached, a `403` status will be returned.\n\nThough the `name` field is required, it does not need to be unique. A unique API key ID will be generated for each key you create and returned in the response body.\n\nIt is not necessary to pass a `scopes` field to the API when creating a key, but you should be aware that omitting the `scopes` field from your request will create a key with \"Full Access\" permissions by default.\n\nSee the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes. An API key's scopes can be updated after creation using the \"Update API keys\" endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name you will use to describe this API Key." - }, - "scopes": { - "type": "array", - "description": "The individual permissions that you are giving to this API Key.", - "items": { - "type": "string" - } - } - }, - "required": ["name"], - "example": { - "name": "My API Key", - "scopes": ["mail.send", "alerts.create", "alerts.read"] - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "api_key": { - "type": "string" - }, - "api_key_id": { - "type": "string" - }, - "name": { - "type": "string" - }, - "scopes": { - "type": "array", - "items": { - "type": "string" - } - } - } - }, - "examples": { - "response": { - "value": { - "api_key": "SG.xxxxxxxx.yyyyyyyy", - "api_key_id": "xxxxxxxx", - "name": "My API Key", - "scopes": ["mail.send", "alerts.create", "alerts.read"] - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_apiKeysErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_apiKeysErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_apiKeysErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "create-api-keys", - "public": true, - "mock": { - "statusCode": 201, - "enabled": false, - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_api_keys", - "summary": "Retrieve all API Keys belonging to the authenticated user", - "tags": ["API Keys"], - "description": "**This endpoint allows you to retrieve all API Keys that belong to the authenticated user.**\n\nA successful response from this API will include all available API keys' names and IDs.\n\nFor security reasons, there is not a way to retrieve the key itself after it's created. If you lose your API key, you must create a new one. Only the \"Create API keys\" endpoint will return a key to you and only at the time of creation.\n\nAn `api_key_id` can be used to update or delete the key, as well as retrieve the key's details, such as its scopes.", - "parameters": [ - { - "name": "limit", - "in": "query", - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/components/schemas/api_key_name_id" - } - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "name": "API Key Name", - "api_key_id": "some-apikey-id" - }, - { - "name": "API Key Name 2", - "api_key_id": "another-apikey-id" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_apikeys", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/api_keys/{api_key_id}": { - "parameters": [ - { - "name": "api_key_id", - "in": "path", - "description": "", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_api_keys-api_key_id", - "summary": "Retrieve an existing API Key", - "tags": ["API Keys"], - "description": "**This endpoint allows you to retrieve a single API key using an `api_key_id`.**\n\nThe endpoint will return a key's name, ID, and scopes. If the API Key ID does not, exist a `404` status will be returned.\n\nSee the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes. An API key's scopes can be updated after creation using the \"Update API keys\" endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/components/schemas/api_key_name_id_scopes" - } - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "name": "API Key Name", - "api_key_id": "some-apikey-id" - }, - { - "name": "API Key Name 2", - "api_key_id": "another-apikey-id" - } - ] - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_apiKeysErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_apiKeysErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_apiKeysErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_apikeys-apikeyid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_api_keys-api_key_id", - "summary": "Update API key name", - "tags": ["API Keys"], - "description": "**This endpoint allows you to update the name of an existing API Key.**\n\nYou must pass this endpoint a JSON request body with a `name` property, which will be used to rename the key associated with the `api_key_id` passed in the URL.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The new name of the API Key." - } - }, - "required": ["name"], - "example": { - "name": "A New Hope" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api_key_name_id" - }, - "examples": { - "response": { - "value": { - "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", - "name": "A New Hope" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_apiKeysErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_apikeys-apikeyid", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "put": { - "operationId": "PUT_api_keys-api_key_id", - "summary": "Update API key name and scopes", - "tags": ["API Keys"], - "description": "**This endpoint allows you to update the name and scopes of a given API key.**\n\nYou must pass this endpoint a JSON request body with a `name` field and a `scopes` array containing at least one scope. The `name` and `scopes` fields will be used to update the key associated with the `api_key_id` in the request URL.\n\nIf you need to update a key's scopes only, pass the `name` field with the key's existing name; the `name` will not be modified. If you need to update a key's name only, use the \"Update API key name\" endpoint.\n\nSee the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "scopes": { - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": ["name"], - "example": { - "name": "Profiles key", - "scopes": ["user.profile.read", "user.profile.update"] - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api_key_name_id_scopes" - }, - "examples": { - "response": { - "value": { - "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", - "name": "Profiles Key", - "scopes": ["user.profile.read", "user.profile.update"] - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_apiKeysErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PUT_apikeys-apikeyid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_api_keys-api_key_id", - "summary": "Delete API keys", - "tags": ["API Keys"], - "description": "**This endpoint allows you to revoke an existing API Key using an `api_key_id`**\n\nAuthentications using a revoked API Key will fail after after some small propogation delay. If the API Key ID does not exist, a `404` status will be returned.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "" - }, - "400": { - "$ref": "#/components/responses/trait_apiKeysErrors_400" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_apikeys-apikeyid", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/scopes": { - "get": { - "operationId": "GET_scopes", - "summary": "Retrieve a list of scopes for which this user has access.", - "tags": ["API Key Permissions"], - "description": "**This endpoint returns a list of all scopes that this user has access to.**\n\nAPI Keys are used to authenticate with [SendGrid's v3 API](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization).\n\nAPI Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access.\n\nThis endpoint returns all the scopes assigned to the key you use to authenticate with it. To retrieve the scopes assigned to another key, you can pass an API key ID to the \"Retrieve an existing API key\" endpoint.\n\nFor a more detailed explanation of how you can use API Key permissions, please visit our [API Keys documentation](https://sendgrid.com/docs/ui/account-and-settings/api-keys/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "The list of scopes for which this user has access.", - "uniqueItems": true, - "items": { - "type": "string" - } - } - }, - "required": ["scopes"] - }, - "examples": { - "response": { - "value": { - "scopes": ["mail.send", "alerts.create", "alerts.read"] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "This 401 response indicates that the user making the call doesn't have the authorization to view the list of scopes.", - "items": { - "type": "object", - "properties": { - "field": { - "description": "This empty field is returned instead of the list of scopes if the user making the call doesn't have the authorization required.", - "type": "string", - "nullable": true - }, - "message": { - "type": "string", - "description": "Explains why the scopes cannot be returned." - } - }, - "required": ["message"] - } - } - }, - "required": ["errors"] - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_scopes", - "public": true, - "mock": { - "dynamic": false, - "statusCode": 200, - "enabled": false - } - } - } - }, - "/user/settings/enforced_tls": { - "get": { - "operationId": "GET_user-settings-enforced_tls", - "summary": "Retrieve current Enforced TLS settings.", - "tags": ["Settings - Enforced TLS"], - "description": "**This endpoint allows you to retrieve your current Enforced TLS settings.**\n\nThe Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate.\n\nIf either `require_tls` or `require_valid_cert` is set to `true`, the recipient must support TLS 1.1 or higher or have a valid certificate. If these conditions are not met, Twilio SendGrid will drop the message and send a block event with “TLS required but not supported” as the description.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/enforced-tls-request-response" - }, - "examples": { - "response": { - "value": { - "require_tls": false, - "require_valid_cert": false - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-settings-enforcedtls", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_user-settings-enforced_tls", - "summary": "Update Enforced TLS settings", - "tags": ["Settings - Enforced TLS"], - "description": "**This endpoint allows you to update your Enforced TLS settings.**\n\nTo require TLS from recipients, set `require_tls` to `true`. If either `require_tls` or `require_valid_cert` is set to `true`, the recipient must support TLS 1.1 or higher or have a valid certificate. If these conditions are not met, Twilio SendGrid will drop the message and send a block event with “TLS required but not supported” as the description.\n\n> Twilio SendGrid supports TLS 1.1 and higher and does not support older versions of TLS due to security vulnerabilities.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/enforced-tls-request-response" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/enforced-tls-request-response" - }, - "examples": { - "response": { - "value": { - "require_tls": true, - "require_valid_cert": false - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_user-settings-enforcedtls", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/access_settings/whitelist": { - "post": { - "operationId": "POST_access_settings-whitelist", - "summary": "Add one or more IPs to the allow list", - "tags": ["IP Access Management"], - "description": "**This endpoint allows you to add one or more allowed IP addresses.**\n\nTo allow one or more IP addresses, pass them to this endpoint in an array. Once an IP address is added to your allow list, it will be assigned an `id` that can be used to remove the address. You can retrieve the ID associated with an IP using the \"Retrieve a list of currently allowed IPs\" endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ips": { - "type": "array", - "description": "An array containing the IP(s) you want to allow.", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "An IP address that you want to allow." - } - }, - "required": ["ip"] - } - } - }, - "required": ["ips"], - "example": { - "ips": [ - { - "ip": "192.168.1.1" - }, - { - "ip": "192.*.*.*" - }, - { - "ip": "192.168.1.3/32" - } - ] - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ip-access-response" - }, - "examples": { - "response": { - "value": { - "result": [ - { - "id": 1, - "ip": "192.168.1.1/32", - "created_at": 1441824715, - "updated_at": 1441824715 - }, - { - "id": 2, - "ip": "192.0.0.0/8", - "created_at": 1441824715, - "updated_at": 1441824715 - }, - { - "id": 3, - "ip": "192.168.1.3/32", - "created_at": 1441824715, - "updated_at": 1441824715 - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_accesssettings-whitelist", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_access_settings-whitelist", - "summary": "Retrieve a list of currently allowed IPs", - "tags": ["IP Access Management"], - "description": "**This endpoint allows you to retrieve a list of IP addresses that are currently allowed to access your account.**\n\nEach IP address returned to you will have `created_at` and `updated_at` dates. Each IP will also be associated with an `id` that can be used to remove the address from your allow list.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ip-access-response" - }, - "examples": { - "response": { - "value": { - "result": [ - { - "id": 1, - "ip": "192.168.1.1/32", - "created_at": 1441824715, - "updated_at": 1441824715 - }, - { - "id": 2, - "ip": "192.168.1.2/32", - "created_at": 1441824715, - "updated_at": 1441824715 - }, - { - "id": 3, - "ip": "192.168.1.3/32", - "created_at": 1441824715, - "updated_at": 1441824715 - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_accesssettings-whitelist", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_access_settings-whitelist", - "summary": "Remove one or more IPs from the allow list", - "tags": ["IP Access Management"], - "description": "**This endpoint allows you to remove one or more IP addresses from your list of allowed addresses.**\n\nTo remove one or more IP addresses, pass this endpoint an array containing the ID(s) associated with the IP(s) you intend to remove. You can retrieve the IDs associated with your allowed IP addresses using the \"Retrieve a list of currently allowed IPs\" endpoint.\n\nIt is possible to remove your own IP address, which will block access to your account. You will need to submit a [support ticket](https://sendgrid.com/docs/ui/account-and-settings/support/) if this happens. For this reason, it is important to double check that you are removing only the IPs you intend to remove when using this endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ids": { - "type": "array", - "description": "An array of the IDs of the IP address that you want to remove from your allow list.", - "items": { - "type": "integer" - } - } - }, - "example": { - "ids": [1, 2, 3] - } - } - } - } - }, - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_accesssettings-whitelist", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/access_settings/activity": { - "get": { - "operationId": "GET_access_settings-activity", - "summary": "Retrieve all recent access attempts", - "tags": ["IP Access Management"], - "description": "**This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.**", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Limits the number of IPs to return.", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "An array containing the IPs that recently attempted to access your account.", - "items": { - "type": "object", - "properties": { - "allowed": { - "type": "boolean", - "description": "Indicates if the IP address was granted access to the account." - }, - "auth_method": { - "type": "string", - "description": "The authentication method used when attempting access." - }, - "first_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the first access attempt was made." - }, - "ip": { - "type": "string", - "description": "The IP addressed used during the access attempt." - }, - "last_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the most recent access attempt was made" - }, - "location": { - "type": "string", - "description": "The geographic location from which the access attempt originated." - } - }, - "required": [ - "allowed", - "auth_method", - "first_at", - "ip", - "last_at", - "location" - ] - } - } - }, - "required": ["result"] - }, - "examples": { - "response": { - "value": { - "result": [ - { - "allowed": false, - "auth_method": "Web", - "first_at": 1444087966, - "ip": "1.1.1.1", - "last_at": 1444406672, - "location": "Australia" - }, - { - "allowed": false, - "auth_method": "Web", - "first_at": 1444087505, - "ip": "1.2.3.48", - "last_at": 1444087505, - "location": "Mukilteo, Washington" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_accesssettings-activity", - "public": true, - "mock": { - "dynamic": false, - "statusCode": 200, - "enabled": false - } - } - } - }, - "/access_settings/whitelist/{rule_id}": { - "parameters": [ - { - "name": "rule_id", - "in": "path", - "description": "The ID of the allowed IP address that you want to retrieve.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_access_settings-whitelist-rule_id", - "summary": "Retrieve a specific allowed IP", - "tags": ["IP Access Management"], - "description": "**This endpoint allows you to retreive a specific IP address that has been allowed to access your account.**\n\nYou must include the ID for the specific IP address you want to retrieve in your call. You can retrieve the IDs associated with your allowed IP addresses using the \"Retrieve a list of currently allowed IPs\" endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ip-access-response" - }, - "examples": { - "response": { - "value": { - "id": 1, - "ip": "192.168.1.1", - "created_at": 1441824715, - "updated_at": 1441824715 - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_accesssettings-whitelist-ruleid", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_access_settings-whitelist-rule_id", - "summary": "Remove a specific IP from the allowed list", - "tags": ["IP Access Management"], - "description": "**This endpoint allows you to remove a specific IP address from your list of allowed addresses.**\n\nWhen removing a specific IP address from your list, you must include the ID in your call. You can retrieve the IDs associated with your allowed IP addresses using the \"Retrieve a list of currently allowed IPs\" endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_accesssettings-whitelist-ruleid", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/sso/certificates": { - "post": { - "operationId": "POST_sso-certificates", - "summary": "Create an SSO Certificate", - "tags": ["Certificates"], - "description": "**This endpoint allows you to create an SSO certificate.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "", - "properties": { - "public_certificate": { - "type": "string", - "description": "This public certificate allows SendGrid to verify that SAML requests it receives are signed by an IdP that it recognizes." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if the certificate is enabled." - }, - "integration_id": { - "type": "string", - "description": "An ID that matches a certificate to a specific IdP integration. This is the `id` returned by the \"Get All SSO Integrations\" endpoint." - } - }, - "required": ["public_certificate", "integration_id"], - "example": { - "public_certificate": "", - "enabled": false, - "integration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-certificate-body" - }, - "examples": { - "response": { - "value": { - "public_certificate": "", - "id": 66138975, - "not_before": 1621289880, - "not_after": 1621289880, - "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_400" - }, - "401": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_401" - }, - "403": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_403" - }, - "429": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_429" - }, - "500": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_500" - } - }, - "x-stoplight": { - "id": "POST_sso-certificates", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/sso/integrations/{integration_id}/certificates": { - "parameters": [ - { - "name": "integration_id", - "in": "path", - "description": "An ID that matches a certificate to a specific IdP integration.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_sso-integrations-integration_id-certificates", - "summary": "Get All SSO Certificates by Integration", - "tags": ["Certificates"], - "description": "**This endpoint allows you to retrieve all your IdP configurations by configuration ID.**\n\nThe `integration_id` expected by this endpoint is the `id` returned in the response by the \"Get All SSO Integrations\" endpoint.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/sso-certificate-body" - } - }, - "examples": { - "response": { - "value": [ - { - "public_certificate": "", - "id": 66138975, - "not_before": 1621289880, - "not_after": 1621289880, - "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" - } - ] - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_400" - }, - "401": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_401" - }, - "403": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_403" - }, - "429": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_429" - }, - "500": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_500" - } - }, - "x-stoplight": { - "id": "GET_sso-integrations-integrationid-certificates", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/sso/certificates/{cert_id}": { - "parameters": [ - { - "name": "cert_id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_sso-certificates-cert_id", - "summary": "Get an SSO Certificate", - "tags": ["Certificates"], - "description": "**This endpoint allows you to retrieve an individual SSO certificate.**", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-certificate-body" - }, - "examples": { - "response": { - "value": { - "public_certificate": "", - "id": 66138975, - "not_before": 1621289880, - "not_after": 1621289880, - "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_400" - }, - "401": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_401" - }, - "403": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_403" - }, - "429": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_429" - }, - "500": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_500" - } - }, - "x-stoplight": { - "id": "GET_sso-certificates-certid", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_sso-certificates-cert_id", - "summary": "Update SSO Certificate", - "tags": ["Certificates"], - "description": "**This endpoint allows you to update an existing certificate by ID.**\n\nYou can retrieve a certificate's ID from the response provided by the \"Get All SSO Integrations\" endpoint.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "public_certificate": { - "type": "string", - "description": "This public certificate allows SendGrid to verify that SAML requests it receives are signed by an IdP that it recognizes." - }, - "enabled": { - "type": "boolean", - "description": "Indicates whether or not the certificate is enabled." - }, - "integration_id": { - "type": "string", - "description": "An ID that matches a certificate to a specific IdP integration." - } - }, - "example": { - "public_certificate": "", - "enabled": false, - "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" - } - } - } - } - }, - "responses": { - "400": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_400" - }, - "401": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_401" - }, - "403": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_403" - }, - "429": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_429" - }, - "500": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_500" - } - }, - "x-stoplight": { - "id": "PATCH_sso-certificates-certid", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_sso-certificates-cert_id", - "summary": "Delete an SSO Certificate", - "tags": ["Certificates"], - "description": "**This endpoint allows you to delete an SSO certificate.**\n\nYou can retrieve a certificate's ID from the response provided by the \"Get All SSO Integrations\" endpoint.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-certificate-body" - }, - "examples": { - "response": { - "value": { - "public_certificate": "", - "id": 66138975, - "not_before": 1621289880, - "not_after": 1621289880, - "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_400" - }, - "401": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_401" - }, - "403": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_403" - }, - "429": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_429" - }, - "500": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_500" - } - }, - "x-stoplight": { - "id": "DELETE_sso-certificates-certid", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/sso/integrations": { - "post": { - "operationId": "POST_sso-integrations", - "summary": "Create an SSO Integration", - "tags": ["Single Sign-On Settings"], - "description": "**This endpoint allows you to create an SSO integration.**", - "requestBody": { - "$ref": "#/components/requestBodies/create-integration-request" - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-integration" - }, - "examples": { - "response": { - "value": { - "name": "Twilio SendGrid", - "enabled": true, - "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", - "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", - "entity_id": "http://www.okta.com/${org.externalKey}", - "last_updated": 1621288964 - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_400" - }, - "401": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_401" - }, - "403": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_403" - }, - "429": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_429" - }, - "500": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_500" - } - }, - "x-stoplight": { - "id": "POST_sso-integrations", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_sso-integrations", - "summary": "Get All SSO Integrations", - "tags": ["Single Sign-On Settings"], - "description": "**This endpoint allows you to retrieve all SSO integrations tied to your Twilio SendGrid account.**\n\nThe IDs returned by this endpoint can be used by the APIs additional endpoints to modify your SSO integrations.", - "parameters": [ - { - "name": "si", - "in": "query", - "description": "If this parameter is set to `true`, the response will include the `completed_integration` field.", - "schema": { - "type": "boolean" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/sso-integration" - } - }, - "examples": { - "response": { - "value": [ - { - "name": "Twilio SendGrid", - "enabled": true, - "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", - "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", - "entity_id": "http://www.okta.com/${org.externalKey}", - "last_updated": 1621288520, - "completed_integration": true, - "id": "b0b98502-9408-4b24-9e3d-31ed7cb15312", - "single_signon_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312", - "audience_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312" - } - ] - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_400" - }, - "401": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_401" - }, - "403": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_403" - }, - "429": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_429" - }, - "500": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_500" - } - }, - "x-stoplight": { - "id": "GET_sso-integrations", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/sso/integrations/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_sso-integrations-id", - "summary": "Get an SSO Integration", - "tags": ["Single Sign-On Settings"], - "description": "**This endpoint allows you to retrieve an SSO integration by ID.**\n\nYou can retrieve the IDs for your configurations from the response provided by the \"Get All SSO Integrations\" endpoint.", - "parameters": [ - { - "name": "si", - "in": "query", - "description": "If this parameter is set to `true`, the response will include the `completed_integration` field.", - "schema": { - "type": "boolean" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-integration" - }, - "examples": { - "response": { - "value": { - "name": "Twilio SendGrid", - "enabled": true, - "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", - "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", - "entity_id": "http://www.okta.com/${org.externalKey}", - "last_updated": 1621288964, - "completed_integration": true, - "id": "b0b98502-9408-4b24-9e3d-31ed7cb15312", - "audience_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_400" - }, - "401": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_401" - }, - "403": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_403" - }, - "429": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_429" - }, - "500": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_500" - } - }, - "x-stoplight": { - "id": "GET_sso-integrations-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_sso-integrations-id", - "summary": "Update an SSO Integration", - "tags": ["Single Sign-On Settings"], - "description": "**This endpoint allows you to modify an exisiting SSO integration.**\n\nYou can retrieve the IDs for your configurations from the response provided by the \"Get All SSO Integrations\" endpoint.", - "parameters": [ - { - "name": "si", - "in": "query", - "description": "If this parameter is set to `true`, the response will include the `completed_integration` field.", - "schema": { - "type": "boolean" - } - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/create-integration-request" - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-integration" - }, - "examples": { - "response": { - "value": { - "name": "Twilio SendGrid", - "enabled": true, - "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", - "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", - "entity_id": "http://www.okta.com/${org.externalKey}", - "last_updated": 1621288964, - "id": "b0b98502-9408-4b24-9e3d-31ed7cb15312", - "single_signon_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312", - "audience_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_400" - }, - "401": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_401" - }, - "403": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_403" - }, - "429": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_429" - }, - "500": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_500" - } - }, - "x-stoplight": { - "id": "PATCH_sso-integrations-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_sso-integrations-id", - "summary": "Delete an SSO Integration", - "tags": ["Single Sign-On Settings"], - "description": "**This endpoint allows you to delete an IdP configuration by ID.**\n\nYou can retrieve the IDs for your configurations from the response provided by the \"Get All SSO Integrations\" endpoint.", - "responses": { - "204": { - "description": "" - }, - "400": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_400" - }, - "401": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_401" - }, - "403": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_403" - }, - "429": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_429" - }, - "500": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_500" - } - }, - "x-stoplight": { - "id": "DELETE_sso-integrations-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/sso/teammates": { - "post": { - "operationId": "POST_sso-teammates", - "summary": "Create SSO Teammate", - "tags": ["Single Sign-On Teammates"], - "description": "**This endpoint allows you to create an SSO Teammate.**\n\nThe email provided for this user will also function as the Teammate’s username.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-teammate-request" - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-teammate-response" - }, - "examples": { - "response": { - "value": { - "first_name": "Jane", - "last_name": "Doe", - "email": "jane_doe@example.com", - "is_read_only": true, - "username": "jane_doe@example.com", - "is_sso": true - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_400" - }, - "401": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_401" - }, - "403": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_403" - }, - "429": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_429" - }, - "500": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_500" - } - }, - "x-stoplight": { - "id": "POST_sso-teammates", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/sso/teammates/{username}": { - "parameters": [ - { - "name": "username", - "in": "path", - "description": "This email address must be the same address assigned to the teammate in your IdP", - "required": true, - "schema": { - "type": "string", - "format": "email" - } - } - ], - "patch": { - "operationId": "PATCH_sso-teammates-username", - "summary": "Edit an SSO Teammate", - "tags": ["Single Sign-On Teammates"], - "description": "**This endpoint allows you to modify an existing SSO Teammate.**\n\nTo turn a teammate into an admin, the request body should contain the `is_admin` field set to `true`. Otherwise, set `is_admin` to false and pass in all the scopes that a teammate should have.\n\nOnly the parent user and Teammates with admin permissions can update another Teammate’s permissions. Admin users can only update permissions.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "scopes": { - "type": "array", - "items": { - "type": "string" - } - }, - "is_admin": { - "type": "boolean" - } - }, - "example": { - "first_name": "Jane", - "last_name": "Doe", - "email": "jane_doe@example.com", - "scopes": [ - "mail.batch.create", - "mail.batch.delete", - "mail.batch.read", - "mail.batch.update", - "mail.send" - ], - "is_admin": false - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-teammates-patch-response" - }, - "examples": { - "response": { - "value": { - "first_name": "Jane", - "last_name": "Doe", - "email": "jane_doe@example.com", - "is_admin": false, - "username": "jane_doe@example.com", - "is_sso": true, - "address": "1234 Fake St.", - "address2": "Suite 5", - "city": "San Francisco", - "state": "CA", - "zip": "94105", - "Country": "United States", - "phone": "+15555555555", - "user_type": "teammate" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_400" - }, - "401": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_401" - }, - "403": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_403" - }, - "429": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_429" - }, - "500": { - "$ref": "#/components/responses/trait_singleSignOnErrorsTrait_500" - } - }, - "x-stoplight": { - "id": "PATCH_sso-teammates-username", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/mail_settings": { - "get": { - "operationId": "GET_mail_settings", - "summary": "Retrieve all mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to retrieve a list of all mail settings.**\n\nEach setting will be returned with an `enabled` status set to `true` or `false` and a short description that explains what the setting does.", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of settings to return.", - "schema": { - "type": "integer" - } - }, - { - "name": "offset", - "in": "query", - "description": "Where in the list of results to begin displaying settings.", - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "The list of all mail settings.", - "items": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The title of the mail setting." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this mail setting is currently enabled." - }, - "name": { - "type": "string", - "description": "The name of the mail setting." - }, - "description": { - "type": "string", - "description": "A description of the mail setting." - } - }, - "required": ["title", "enabled", "name", "description"] - } - } - }, - "required": ["result"] - }, - "examples": { - "response": { - "value": { - "result": [ - { - "title": "Address Whitelist", - "enabled": false, - "name": "address_whitelist", - "description": "Address / domains that should never have email suppressed." - }, - { - "title": "Bounce Purge", - "enabled": false, - "name": "bounce_purge", - "description": "Allows you to automatically purge bounce records from SendGrid after a specified number of days." - }, - { - "title": "Event Notification", - "enabled": true, - "name": "event_notify", - "description": "Controls notifications for events, such as bounces, clicks, and opens." - }, - { - "title": "Footer", - "enabled": false, - "name": "footer", - "description": "Allows you to add a custom footer to outgoing email." - }, - { - "title": "Forward Bounce", - "enabled": true, - "name": "forward_bounce", - "description": "Allows you to forward bounces to a specific email address." - }, - { - "title": "Forward Spam", - "enabled": false, - "name": "forward_spam", - "description": "Allows for a copy of spam reports to be forwarded to an email address." - }, - { - "title": "Legacy Email Template", - "enabled": true, - "name": "template", - "description": "Allows you to customize your outgoing HTML emails." - }, - { - "title": "Plain Content", - "enabled": false, - "name": "plain_content", - "description": "Convert your plain text emails to HTML." - }, - { - "title": "Spam Checker", - "enabled": true, - "name": "spam_check", - "description": "Check outbound messages for spam content." - } - ] - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mailsettings", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/mail_settings/address_whitelist": { - "patch": { - "operationId": "PATCH_mail_settings-address_whitelist", - "summary": "Update address whitelist mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to update your current email address whitelist settings.**\n\nYou can select whether or not this setting should be enabled by assigning the `enabled` field a `true` or `false` value.\n\nPassing only the `enabled` field to this endpoint will not alter your current `list` of whitelist entries. However, any modifications to your `list` of entries will overwrite the entire list. For this reason, you must included all existing entries you wish to retain in your `list` in addition to any new entries you intend to add. To remove one or more `list` entries, pass a `list` with only the entries you wish to retain.\n\nYou should not add generic domains such as `gmail.com` or `yahoo.com` in your `list` because your emails will not honor recipients' unsubscribes. This may cause a legal violation of [CAN-SPAM](https://sendgrid.com/docs/glossary/can-spam/) and could damage your sending reputation.\n\nThe Address Whitelist setting allows you to specify email addresses or domains for which mail should never be suppressed.\n\nFor example, if you own the domain `example.com`, and one or more of your recipients use `email@example.com` addresses, placing `example.com` in the address whitelist setting instructs Twilio SendGrid to ignore all bounces, blocks, and unsubscribes logged for that domain. In other words, all bounces, blocks, and unsubscribes will still be sent to `example.com` as if they were sent under normal sending conditions.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if your email address whitelist is enabled." - }, - "list": { - "type": "array", - "description": "Either a single email address that you want whitelisted or a domain, for which all email addresses belonging to this domain will be whitelisted.", - "items": { - "type": "string" - } - } - }, - "example": { - "enabled": true, - "list": ["email1@example.com", "example.com"] - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_address_whitelabel" - }, - "examples": { - "response": { - "value": { - "enabled": true, - "list": ["email1@example.com"] - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_mailsettings-addresswhitelist", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_mail_settings-address_whitelist", - "summary": "Retrieve address whitelist mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to retrieve your current email address whitelist settings.**\n\nThe Address Whitelist setting allows you to specify email addresses or domains for which mail should never be suppressed.\n\nFor example, if you own the domain `example.com`, and one or more of your recipients use `email@example.com` addresses, placing `example.com` in the address whitelist setting instructs Twilio SendGrid to ignore all bounces, blocks, and unsubscribes logged for that domain. In other words, all bounces, blocks, and unsubscribes will still be sent to `example.com` as if they were sent under normal sending conditions.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_address_whitelabel" - }, - "examples": { - "response": { - "value": { - "enabled": true, - "list": ["example.com", "jane_doe@example1.com"] - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mailsettings-addresswhitelist", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/mail_settings/footer": { - "patch": { - "operationId": "PATCH_mail_settings-footer", - "summary": "Update footer mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to update your current Footer mail settings.**\n\nThe Footer setting will insert a custom footer at the bottom of your text and HTML email message bodies.\n\nYou can insert your HTML or plain text directly using this endpoint, or you can create the footer using the [Mail Settings menu in the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_footer" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_footer" - }, - "examples": { - "response": { - "value": { - "enabled": true, - "html_content": "

Ahoy, World!

\n", - "plain_content": "" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_mailsettings-footer", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_mail_settings-footer", - "summary": "Retrieve footer mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to retrieve your current Footer mail settings.**\n\nThe Footer setting will insert a custom footer at the bottom of your text and HTML email message bodies.\n\nYou can insert your HTML or plain text directly using the \"Update footer mail settings\" endpoint, or you can create the footer using the [Mail Settings menu in the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_footer" - }, - "examples": { - "response": { - "value": { - "enabled": true, - "html_content": "

Ahoy, World!

\n", - "plain_content": "" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mailsettings-footer", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/mail_settings/forward_spam": { - "patch": { - "operationId": "PATCH_mail_settings-forward_spam", - "summary": "Update forward spam mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to update your current Forward Spam mail settings.**\n\nEnabling the Forward Spam setting allows you to specify `email` addresses to which spam reports will be forwarded. You can set multiple addresses by passing this endpoint a comma separated list of emails in a single string.\n\n```\n{\n \"email\": \"address1@example.com, address2@exapmle.com\",\n \"enabled\": true\n}\n```\n\nThe Forward Spam setting may also be used to receive emails sent to `abuse@` and `postmaster@` role addresses if you have authenticated your domain.\n\nFor example, if you authenticated `example.com` as your root domain and set a custom return path of `sub` for that domain, you could turn on Forward Spam, and any emails sent to `abuse@sub.example.com` or `postmaster@sub.example.com` would be forwarded to the email address you entered in the `email` field.\n\nYou can authenticate your domain using the \"Authenticate a domain\" endpoint or in the [Sender Authentication section of the Twilio SendGrid App](https://app.sendgrid.com/settings/sender_auth). You can also configure the Forward Spam mail settings in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_forward_spam" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_forward_spam" - }, - "examples": { - "response": { - "value": { - "email": "abuse@example.com", - "enabled": true - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_mailsettings-forwardspam", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_mail_settings-forward_spam", - "summary": "Retrieve forward spam mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to retrieve your current Forward Spam mail settings.**\n\nEnabling the Forward Spam setting allows you to specify `email` addresses to which spam reports will be forwarded. This endpoint returns any email address(es) you have set to receive forwarded spam and an `enabled` status indicating if the setting is active.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_forward_spam" - }, - "examples": { - "response": { - "value": { - "email": "abuse@example.com", - "enabled": true - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mailsettings-forwardspam", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/mail_settings/template": { - "patch": { - "operationId": "PATCH_mail_settings-template", - "summary": "Update template mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to update your current legacy email template settings.**\n\nThis setting refers to our original email templates. We currently support more fully featured [Dynamic Transactional Templates](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/).\n\nThe legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. For instructions on using legacy templates, see how to [\"Create and Edit Legacy Transactional Templates](https://sendgrid.com/docs/ui/sending-email/create-and-edit-legacy-transactional-templates/). For help migrating to our current template system, see [\"Migrating from Legacy Templates\"](https://sendgrid.com/docs/ui/sending-email/migrating-from-legacy-templates/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if you want to enable the legacy email template mail setting." - }, - "html_content": { - "type": "string", - "description": "The new HTML content for your legacy email template." - } - }, - "example": { - "enabled": true, - "html_content": "<% body %>" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the legacy email template mail setting is enabled." - }, - "html_content": { - "type": "string", - "description": "The HTML content of your legacy email template." - } - }, - "required": ["enabled", "html_content"] - }, - "examples": { - "response": { - "value": { - "enabled": false, - "html_content": "

<% body %>Example

\n" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_mailsettings-template", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_mail_settings-template", - "summary": "Retrieve legacy template mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to retrieve your current legacy email template settings.**\n\nThis setting refers to our original email templates. We currently support more fully featured [Dynamic Transactional Templates](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/).\n\nThe legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. For instructions on using legacy templates, see how to [\"Create and Edit Legacy Transactional Templates](https://sendgrid.com/docs/ui/sending-email/create-and-edit-legacy-transactional-templates/). For help migrating to our current template system, see [\"Migrating from Legacy Templates\"](https://sendgrid.com/docs/ui/sending-email/migrating-from-legacy-templates/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_template" - }, - "examples": { - "response": { - "value": { - "enabled": false, - "html_content": "

<% body %>Example

\n" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mailsettings-template", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/mail_settings/bounce_purge": { - "patch": { - "operationId": "PATCH_mail_settings-bounce_purge", - "summary": "Update bounce purge mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to update your current bounce and purge settings.**\n\nThe Bounce Perge setting allows you to set a schedule that Twilio SendGrid will use to automatically delete contacts from your soft and hard bounce suppression lists. The schedule is set in full days by assigning the number of days, an integer, to the `soft_bounces` and/or `hard_bounces` fields.\n\nA hard bounce occurs when an email message has been returned to the sender because the recipient's address is invalid. A hard bounce might occur because the domain name doesn't exist or because the recipient is unknown.\n\nA soft bounce occurs when an email message reaches the recipient's mail server but is bounced back undelivered before it actually reaches the recipient. A soft bounce might occur because the recipient's inbox is full.\n\nYou can also manage this setting in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). You can manage your bounces manually using the [Bounces API](https://sendgrid.api-docs.io/v3.0/bounces-api) or the [Bounces menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/bounces).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_bounce_purge" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_bounce_purge" - }, - "examples": { - "response": { - "value": { - "enabled": false, - "hard_bounces": 5, - "soft_bounces": 5 - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_mailsettings-bouncepurge", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_mail_settings-bounce_purge", - "summary": "Retrieve bounce purge mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to retrieve your current bounce and purge settings.**\n\nThe Bounce Perge setting allows you to set a schedule that Twilio SendGrid will use to automatically delete contacts from your soft and hard bounce suppression lists.\n\nA hard bounce occurs when an email message has been returned to the sender because the recipient's address is invalid. A hard bounce might occur because the domain name doesn't exist or because the recipient is unknown.\n\nA soft bounce occurs when an email message reaches the recipient's mail server but is bounced back undelivered before it actually reaches the recipient. A soft bounce might occur because the recipient's inbox is full.\n\nYou can also manage this setting in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). You can manage your bounces manually using the [Bounces API](https://sendgrid.api-docs.io/v3.0/bounces-api) or the [Bounces menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/bounces).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_bounce_purge" - }, - "examples": { - "response": { - "value": { - "enabled": false, - "soft_bounces": 5, - "hard_bounces": 5 - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mailsettings-bouncepurge", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/mail_settings/forward_bounce": { - "patch": { - "operationId": "PATCH_mail_settings-forward_bounce", - "summary": "Update forward bounce mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to update your current bounce forwarding mail settings.**\n\nEnabling the Forward Bounce setting allows you to specify an `email` address to which bounce reports will be forwarded.\n\nYou can also configure the Forward Spam mail settings in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_forward_bounce" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_forward_bounce" - }, - "examples": { - "response": { - "value": { - "email": "bounces@example.com", - "enabled": true - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_mailsettings-forwardbounce", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_mail_settings-forward_bounce", - "summary": "Retrieve forward bounce mail settings", - "tags": ["Settings - Mail"], - "description": "**This endpoint allows you to retrieve your current bounce forwarding mail settings.**\n\nEnabling the Forward Bounce setting allows you to specify `email` addresses to which bounce reports will be forwarded. This endpoint returns the email address you have set to receive forwarded bounces and an `enabled` status indicating if the setting is active.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/mail_settings_forward_bounce" - }, - "examples": { - "response": { - "value": { - "enabled": true, - "email": "bounces@example.com" - } - } - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_makoErrorResponse_400" - }, - "401": { - "$ref": "#/components/responses/trait_makoErrorResponse_401" - }, - "403": { - "$ref": "#/components/responses/trait_makoErrorResponse_403" - }, - "404": { - "$ref": "#/components/responses/trait_makoErrorResponse_404" - }, - "500": { - "$ref": "#/components/responses/trait_makoErrorResponse_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mailsettings-forwardbounce", - "public": true, - "mock": { - "dynamic": false, - "statusCode": 200, - "enabled": false - } - } - } - }, - "/partner_settings/new_relic": { - "patch": { - "operationId": "PATCH_partner_settings-new_relic", - "summary": "Updates New Relic partner settings.", - "tags": ["Settings - Partner"], - "description": "**This endpoint allows you to update or change your New Relic partner settings.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/).\n\nBy integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [SendGrid for New Relic documentation](https://sendgrid.com/docs/ui/analytics-and-reporting/tracking-stats-using-new-relic/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "license_key": { - "type": "string", - "description": "The license key for your New Relic account." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this partner setting is enabled." - }, - "enable_subuser_statistics": { - "type": "boolean", - "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard." - } - }, - "example": { - "license_key": "", - "enabled": true, - "enable_subuser_statistics": true - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/partner_settings_new_relic" - }, - "examples": { - "response": { - "value": { - "enable_subuser_statistics": true, - "enabled": true, - "license_key": "" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_partnersettings-newrelic", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_partner_settings-new_relic", - "summary": "Returns all New Relic partner settings.", - "tags": ["Settings - Partner"], - "description": "**This endpoint allows you to retrieve your current New Relic partner settings.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/).\n\nBy integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [SendGrid for New Relic documentation](https://sendgrid.com/docs/ui/analytics-and-reporting/tracking-stats-using-new-relic/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/partner_settings_new_relic" - }, - "examples": { - "response": { - "value": { - "enable_subuser_statistics": false, - "enabled": true, - "license_key": "" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_partnersettings-newrelic", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/partner_settings": { - "get": { - "operationId": "GET_partner_settings", - "summary": "Returns a list of all partner settings.", - "tags": ["Settings - Partner"], - "description": "**This endpoint allows you to retrieve a list of all partner settings that you can enable.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/).", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of settings to return per page.", - "schema": { - "type": "integer" - } - }, - { - "name": "offset", - "in": "query", - "description": "The paging offset.", - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The title of the partner." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this partner setting has been enabled." - }, - "name": { - "type": "string", - "description": "The name of the partner setting." - }, - "description": { - "type": "string", - "description": "A description of this partner setting." - } - }, - "required": ["title", "enabled", "name", "description"] - } - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "title": "Partner title", - "enabled": true, - "name": "partner_name", - "description": "A description of a partner." - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_partnersettings", - "public": true, - "mock": { - "dynamic": false, - "statusCode": 200, - "enabled": false - } - } - } - }, - "/teammates": { - "post": { - "operationId": "POST_v3-teammates", - "summary": "Invite teammate", - "tags": ["Teammates"], - "description": "**This endpoint allows you to invite a Teammate to your account via email.**\n\nYou can set a Teammate's initial permissions using the `scopes` array in the request body. Teammate's will receive a minimum set of scopes from Twilio SendGrid that are necessary for the Teammate to function.\n\n**Note:** A teammate invite will expire after 7 days, but you may resend the invitation at any time to reset the expiration date.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "New teammate's email", - "minLength": 5, - "maxLength": 255, - "pattern": "^.*@.*\\..*" - }, - "scopes": { - "type": "array", - "description": "Set to specify list of scopes that teammate should have. Should be empty if teammate is an admin.", - "items": { - "type": "string" - } - }, - "is_admin": { - "type": "boolean", - "default": false, - "description": "Set to true if teammate should be an admin user" - } - }, - "required": ["email", "scopes", "is_admin"], - "example": { - "email": "teammate1@example.com", - "scopes": ["user.profile.read", "user.profile.update"], - "is_admin": false - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "token": { - "type": "string", - "description": "Token to identify invite" - }, - "email": { - "type": "string", - "description": "Teammate's email address" - }, - "scopes": { - "type": "array", - "description": "Initial set of permissions to give to teammate if they accept the invite", - "items": {} - }, - "is_admin": { - "type": "boolean", - "description": "Set to true if teammate should have admin privileges" - } - } - }, - "examples": { - "response": { - "value": { - "email": "teammate1@example.com", - "scopes": ["user.profile.read", "user.profile.update"], - "is_admin": false - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_v3-teammates", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_v3-teammates", - "summary": "Retrieve all teammates", - "tags": ["Teammates"], - "description": "**This endpoint allows you to retrieve a list of all current Teammates.**\n\nYou can limit the number of results returned using the `limit` query paramater. To return results from a specific Teammate, use the `offset` paramter. The Response Headers will include pagination info.", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Number of items to return", - "schema": { - "type": "integer", - "minimum": 0, - "maximum": 500, - "default": 500 - } - }, - { - "name": "offset", - "in": "query", - "description": "Paging offset", - "schema": { - "type": "integer", - "minimum": 0, - "default": 0 - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "Teammate's username" - }, - "email": { - "type": "string", - "description": "Teammate's email" - }, - "first_name": { - "type": "string", - "description": "Teammate's first name" - }, - "last_name": { - "type": "string", - "description": "Teammate's last name" - }, - "user_type": { - "type": "string", - "description": "Indicate the type of user: owner user, teammate admin user, or normal teammate", - "enum": ["admin", "owner", "teammate"] - }, - "is_admin": { - "type": "boolean", - "description": "Set to true if teammate has admin privileges" - }, - "phone": { - "type": "string", - "description": "(optional) Teammate's phone number" - }, - "website": { - "type": "string", - "description": "(optional) Teammate's website" - }, - "address": { - "type": "string", - "description": "(optional) Teammate's address" - }, - "address2": { - "type": "string", - "description": "(optional) Teammate's address" - }, - "city": { - "type": "string", - "description": "(optional) Teammate's city" - }, - "state": { - "type": "string", - "description": "(optional) Teammate's state" - }, - "zip": { - "type": "string", - "description": "(optional) Teammate's zip" - }, - "country": { - "type": "string", - "description": "(optional) Teammate's country" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "results": [ - { - "username": "teammate1", - "email": "teammate1@example.com", - "first_name": "Jane", - "last_name": "Doe", - "user_type": "owner", - "is_admin": true, - "phone": "123-345-3453", - "website": "www.example.com", - "company": "ACME Inc.", - "address": "123 Acme St", - "address2": "", - "city": "City", - "state": "CA", - "country": "USA", - "zip": "12345" - }, - { - "username": "teammate2", - "email": "teammate2@example.com", - "first_name": "John", - "last_name": "Doe", - "user_type": "teammate", - "is_admin": false, - "phone": "123-345-3453", - "website": "www.example.com", - "company": "ACME Inc.", - "address": "123 Acme St", - "address2": "", - "city": "City", - "state": "CA", - "country": "USA", - "zip": "12345" - }, - { - "username": "teammate3", - "email": "teammate3@example.com", - "first_name": "Steve", - "last_name": "Doe", - "user_type": "admin", - "is_admin": true, - "phone": "123-345-3453", - "website": "www.example.com", - "company": "ACME Inc.", - "address": "123 Acme St", - "address2": "", - "city": "City", - "state": "CA", - "country": "USA", - "zip": "12345" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_v3-teammates", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/teammates/pending/{token}/resend": { - "parameters": [ - { - "name": "token", - "in": "path", - "description": "The token for the invite that you want to resend.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "post": { - "operationId": "POST_v3-teammates-pending-token-resend", - "summary": "Resend teammate invite", - "tags": ["Teammates"], - "description": "**This endpoint allows you to resend a Teammate invitation.**\n\nTeammate invitations will expire after 7 days. Resending an invitation will reset the expiration date.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "token": { - "type": "string", - "description": "ID to identify invite" - }, - "email": { - "type": "string", - "description": "Teammate's email address" - }, - "scopes": { - "type": "array", - "description": "Initial set of permissions to give to teammate if they accept the invite", - "items": { - "type": "string" - } - }, - "is_admin": { - "type": "boolean", - "description": "Set to true if teammate should have admin privileges" - } - } - }, - "examples": { - "response": { - "value": { - "pending_id": "abc123abc", - "email": "teammate1@example.com", - "scopes": ["user.profile.read", "user.profile.update"], - "is_admin": false - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "invalid pending key", - "field": "pending_key" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_v3-teammates-pending-token-resend", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/scopes/requests": { - "get": { - "operationId": "GET_v3-scopes-requests", - "summary": "Retrieve access requests", - "tags": ["Teammates"], - "description": "**This endpoint allows you to retrieve a list of all recent access requests.**\n\nThe Response Header's `link` parameter will include pagination info.", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Optional field to limit the number of results returned.", - "schema": { - "type": "integer", - "default": 50 - } - }, - { - "name": "offset", - "in": "query", - "description": "Optional beginning point in the list to retrieve from.", - "schema": { - "type": "integer", - "default": 0 - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "Request ID" - }, - "scope_group_name": { - "type": "string", - "description": "Name of group of scopes associated to page teammate is requesting access to" - }, - "username": { - "type": "string", - "description": "Teammate's username" - }, - "email": { - "type": "string", - "description": "Teammate's email" - }, - "first_name": { - "type": "string", - "description": "Teammate's first name" - }, - "last_name": { - "type": "string", - "description": "Teammate's last name" - } - } - } - }, - "examples": { - "response": { - "value": [ - { - "id": 1, - "scope_group_name": "Mail Settings", - "username": "teammate1", - "email": "teammate1@example.com", - "first_name": "Teammate", - "last_name": "One" - }, - { - "id": 2, - "scope_group_name": "Stats", - "username": "teammate2", - "email": "teammate2@example.com", - "first_name": "Teammate", - "last_name": "Two" - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_v3-scopes-requests", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/teammates/pending": { - "get": { - "operationId": "GET_v3-teammates-pending", - "summary": "Retrieve all pending teammates", - "tags": ["Teammates"], - "description": "**This endpoint allows you to retrieve a list of all pending Teammate invitations.**\n\nEach teammate invitation is valid for 7 days. Users may resend the invitation to refresh the expiration date.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "Email address teammate invite will be sent to" - }, - "scopes": { - "type": "array", - "description": "List of permissions to give teammate if they accept", - "items": { - "type": "string" - } - }, - "is_admin": { - "type": "boolean", - "description": "Set to true to indicate teammate should have the same set of permissions as parent user" - }, - "token": { - "type": "string", - "description": "Invitation token used to identify user" - }, - "expiration_date": { - "type": "integer", - "description": "timestamp indicates when invite will expire. Expiration is 7 days after invite creation" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "email": "user1@example.com", - "scopes": ["user.profile.read", "user.profile.edit"], - "is_admin": false, - "pending_id": "abcd123abc", - "expiration_date": 1456424263 - }, - { - "email": "user2@example.com", - "scopes": [], - "is_admin": true, - "pending_id": "bcde234bcd", - "expiration_date": 1456424263 - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_v3-teammates-pending", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/teammates/{username}": { - "parameters": [ - { - "name": "username", - "in": "path", - "description": "The username of the teammate that you want to retrieve.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_v3-teammates-username", - "summary": "Retrieve specific teammate", - "tags": ["Teammates"], - "description": "**This endpoint allows you to retrieve a specific Teammate by username.**\n\nYou can retrieve the username's for each of your Teammates using the \"Retrieve all Teammates\" endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "Teammate's username" - }, - "first_name": { - "type": "string", - "description": "Teammate's first name" - }, - "last_name": { - "type": "string", - "description": "Teammate's last name" - }, - "email": { - "type": "string", - "description": "Teammate's email" - }, - "scopes": { - "type": "array", - "description": "Scopes associated to teammate", - "items": {} - }, - "user_type": { - "type": "string", - "description": "Indicate the type of user: account owner, teammate admin user, or normal teammate", - "enum": ["admin", "owner", "teammate"] - }, - "is_admin": { - "type": "boolean", - "description": "Set to true if teammate has admin privileges" - }, - "phone": { - "type": "string", - "description": "(optional) Teammate's phone number" - }, - "website": { - "type": "string", - "description": "(optional) Teammate's website" - }, - "address": { - "type": "string", - "description": "(optional) Teammate's address" - }, - "address2": { - "type": "string", - "description": "(optional) Teammate's address" - }, - "city": { - "type": "string", - "description": "(optional) Teammate's city" - }, - "state": { - "type": "string", - "description": "(optional) Teammate's state" - }, - "zip": { - "type": "string", - "description": "(optional) Teammate's zip" - }, - "country": { - "type": "string", - "description": "(optional) Teammate's country" - } - } - }, - "examples": { - "response": { - "value": { - "username": "teammate1", - "first_name": "Jane", - "last_name": "Doe", - "email": "teammate1@example.com", - "scopes": ["user.profile.read", "user.profile.update", "..."], - "user_type": "admin", - "is_admin": true, - "phone": "123-345-3453", - "website": "www.example.com", - "company": "ACME Inc.", - "address": "123 Acme St", - "address2": "", - "city": "City", - "state": "CA", - "country": "USA", - "zip": "12345" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_v3-teammates-username", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_v3-teammates-username", - "summary": "Update teammate's permissions", - "tags": ["Teammates"], - "description": "**This endpoint allows you to update a teammate’s permissions.**\n\nTo turn a teammate into an admin, the request body should contain an `is_admin` set to `true`. Otherwise, set `is_admin` to `false` and pass in all the scopes that a teammate should have.\n\n**Only the parent user or other admin teammates can update another teammate’s permissions.**\n\n**Admin users can only update permissions.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "Provide list of scopes that should be given to teammate. If specifying list of scopes, is_admin should be set to False.", - "items": { - "type": "string" - } - }, - "is_admin": { - "type": "boolean", - "description": "Set to True if this teammate should be promoted to an admin user. If True, scopes should be an empty array." - } - }, - "required": ["scopes", "is_admin"], - "example": { - "scopes": ["user.profile.read", "user.profile.edit"], - "is_admin": false - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "Teammate's username" - }, - "first_name": { - "type": "string", - "description": "Teammate's first name" - }, - "last_name": { - "type": "string", - "description": "Teammate's last name" - }, - "email": { - "type": "string", - "description": "Teammate's email address" - }, - "scopes": { - "type": "array", - "description": "Scopes given to teammate", - "items": { - "type": "string" - } - }, - "user_type": { - "type": "string", - "description": "Indicate the type of user: owner user, teammate admin user, or normal teammate", - "enum": ["admin", "owner", "teammate"] - }, - "is_admin": { - "type": "boolean", - "description": "Set to true if teammate has admin priveleges" - }, - "phone": { - "type": "string", - "description": "(optional) Teammate's phone number" - }, - "website": { - "type": "string", - "description": "(optional) Teammate's website" - }, - "address": { - "type": "string", - "description": "(optional) Teammate's address" - }, - "address2": { - "type": "string", - "description": "(optional) Teammate's address" - }, - "city": { - "type": "string", - "description": "(optional) Teammate's city" - }, - "state": { - "type": "string", - "description": "(optional) Teammate's state" - }, - "zip": { - "type": "string", - "description": "(optional) Teammate's zip" - }, - "country": { - "type": "string", - "description": "(optional) Teammate's country" - } - } - }, - "examples": { - "response": { - "value": { - "username": "teammate1", - "first_name": "Jane", - "last_name": "Doe", - "email": "teammate1@example.com", - "scopes": ["user.profile.read", "user.profile.edit"], - "user_type": "teammate", - "is_admin": false, - "phone": "123-345-3453", - "website": "www.example.com", - "company": "ACME Inc.", - "address": "123 Acme St", - "address2": "", - "city": "City", - "state": "CA", - "country": "USA", - "zip": "12345" - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "one or more of given scopes are invalid", - "field": "scopes" - } - ] - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "username not found", - "field": "username" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_v3-teammates-username", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_v3-teammates-username", - "summary": "Delete teammate", - "tags": ["Teammates"], - "description": "**This endpoint allows you to delete a teammate.**\n\n**Only the parent user or an admin teammate can delete another teammate.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "username not found", - "field": "username" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_v3-teammates-username", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/scopes/requests/{request_id}/approve": { - "parameters": [ - { - "name": "request_id", - "in": "path", - "description": "The ID of the request that you want to approve.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "patch": { - "operationId": "PATCH_v3-scopes-requests-approve-id", - "summary": "Approve access request", - "tags": ["Teammates"], - "description": "**This endpoint allows you to approve an access attempt.**\n\n**Note:** Only teammate admins may approve another teammate’s access request.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "scope_group_name": { - "type": "string", - "description": "name of feature teammate will be given access to" - } - } - }, - "examples": { - "response": { - "value": { - "scope_group_name": "Stats" - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_v3-scopes-requests-approve-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/scopes/requests/{request_id}": { - "parameters": [ - { - "name": "request_id", - "in": "path", - "description": "The ID of the request that you want to deny.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "delete": { - "operationId": "DELETE_v3-scopes-requests-request_id", - "summary": "Deny access request", - "tags": ["Teammates"], - "description": "**This endpoint allows you to deny an attempt to access your account.**\n\n**Note:** Only teammate admins may delete a teammate's access request.", - "responses": { - "204": { - "description": "" - }, - "401": { - "description": "" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "Cannot find request", - "field": "request_id" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_v3-scopes-requests-request_id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/teammates/pending/{token}": { - "parameters": [ - { - "name": "token", - "in": "path", - "description": "The token for the invite you want to delete.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "delete": { - "operationId": "DELETE_v3-teammates-pending-token", - "summary": "Delete pending teammate", - "tags": ["Teammates"], - "description": "**This endpoint allows you to delete a pending teammate invite.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_v3-teammates-pending-token", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/alerts": { - "post": { - "operationId": "POST_alerts", - "summary": "Create a new Alert", - "tags": ["Alerts"], - "description": "**This endpoint allows you to create a new alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. There are two types of alerts that can be created with this endpoint:\n\n* `usage_limit` allows you to set the threshold at which an alert will be sent.\n* `stats_notification` allows you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", - "parameters": [ - { - "name": "Authorization", - "in": "header", - "schema": { - "type": "string" - } - }, - { - "name": "on-behalf-of", - "in": "header", - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of alert you want to create. Can be either usage_limit or stats_notification.\nExample: usage_limit", - "enum": ["stats_notification", "usage_limit"] - }, - "email_to": { - "type": "string", - "description": "The email address the alert will be sent to.\nExample: test@example.com", - "format": "email", - "nullable": true - }, - "frequency": { - "type": "string", - "description": "Required for stats_notification. How frequently the alert will be sent.\nExample: daily" - }, - "percentage": { - "type": "integer", - "description": "Required for usage_alert. When this usage threshold is reached, the alert will be sent.\nExample: 90" - } - }, - "required": ["type", "email_to"], - "example": { - "type": "stats_notification", - "email_to": "example@example.com", - "frequency": "daily" - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was created." - }, - "email_to": { - "type": "string", - "description": "The email address that the alert will be sent to.", - "format": "email" - }, - "frequency": { - "type": "string", - "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, \"daily\", \"weekly\", or \"monthly\"." - }, - "id": { - "type": "integer", - "description": "The ID of the alert." - }, - "type": { - "type": "string", - "description": "The type of alert." - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was last modified." - }, - "percentage": { - "type": "integer", - "description": "\"If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." - } - }, - "required": ["created_at", "email_to", "id", "type", "updated_at"] - }, - "examples": { - "response": { - "value": { - "created_at": 1451520930, - "email_to": "test@example.com", - "frequency": "daily", - "id": 48, - "type": "stats_notification", - "updated_at": 1451520930 - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_alerts", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_alerts", - "summary": "Retrieve all alerts", - "tags": ["Alerts"], - "description": "**This endpoint allows you to retrieve all of your alerts.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", - "parameters": [ - { - "name": "Authorization", - "in": "header", - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "description": "The list of alerts.", - "items": { - "type": "object", - "properties": { - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was created." - }, - "email_to": { - "type": "string", - "description": "The email address that the alert will be sent to." - }, - "id": { - "type": "integer", - "description": "The ID of the alert." - }, - "percentage": { - "type": "integer", - "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." - }, - "type": { - "type": "string", - "description": "The type of alert.", - "enum": ["usage_limit", "stats_notification"] - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was last modified." - }, - "frequency": { - "type": "string", - "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, \"daily\", \"weekly\", or \"monthly\"." - } - }, - "required": ["created_at", "email_to", "id", "type"] - } - }, - "examples": { - "response": { - "value": [ - { - "created_at": 1451498784, - "email_to": "example1@example.com", - "id": 46, - "percentage": 90, - "type": "usage_limit", - "updated_at": 1451498784 - }, - { - "created_at": 1451498812, - "email_to": "example2@example.com", - "frequency": "monthly", - "id": 47, - "type": "stats_notification", - "updated_at": 1451498812 - }, - { - "created_at": 1451520930, - "email_to": "example3@example.com", - "frequency": "daily", - "id": 48, - "type": "stats_notification", - "updated_at": 1451520930 - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_alerts", - "beforeScript": "function (ctx, request) {\n // Your javascript code here.+\n request.header.set('User-Agent', 'sendgrid/stoplightLocs');\n}", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/alerts/{alert_id}": { - "parameters": [ - { - "name": "alert_id", - "in": "path", - "description": "The ID of the alert you would like to retrieve.", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "get": { - "operationId": "GET_alerts-alert_id", - "summary": "Retrieve a specific alert", - "tags": ["Alerts"], - "description": "**This endpoint allows you to retrieve a specific alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", - "parameters": [ - { - "name": "Authorization", - "in": "header", - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was created." - }, - "email_to": { - "type": "string", - "description": "The email address that the alert will be sent to." - }, - "frequency": { - "type": "string", - "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\"." - }, - "id": { - "type": "integer", - "description": "The ID of the alert." - }, - "type": { - "type": "string", - "description": "The type of alert.", - "enum": ["usage_alert", "stats_notification"] - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was last modified." - }, - "percentage": { - "type": "integer", - "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." - } - }, - "required": ["created_at", "email_to", "id", "type", "updated_at"] - }, - "examples": { - "response": { - "value": { - "created_at": 1451520930, - "email_to": "example@example.com", - "frequency": "daily", - "id": 48, - "type": "stats_notification", - "updated_at": 1451520930 - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_alerts-alertid", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_alerts-alert_id", - "summary": "Delete an alert", - "tags": ["Alerts"], - "description": "**This endpoint allows you to delete an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_alerts-alertid", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_alerts-alert_id", - "summary": "Update an alert", - "tags": ["Alerts"], - "description": "**This endpoint allows you to update an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "email_to": { - "type": "string", - "description": "The new email address you want your alert to be sent to.\nExample: test@example.com" - }, - "frequency": { - "type": "string", - "description": "The new frequency at which to send the stats_notification alert.\nExample: monthly" - }, - "percentage": { - "type": "integer", - "description": "The new percentage threshold at which the usage_limit alert will be sent.\nExample: 90" - } - }, - "example": { - "email_to": "example@example.com" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was created." - }, - "email_to": { - "type": "string", - "description": "The email address that the alert will be sent to." - }, - "frequency": { - "type": "string", - "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\"." - }, - "id": { - "type": "integer", - "description": "The ID of the alert." - }, - "type": { - "type": "string", - "description": "The type of alert.", - "enum": ["usage_alert", "stats_notification"] - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was last modified." - }, - "percentage": { - "type": "integer", - "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." - } - }, - "required": ["created_at", "email_to", "id", "type", "updated_at"] - }, - "examples": { - "response": { - "value": { - "created_at": 1451520930, - "email_to": "example@example.com", - "frequency": "daily", - "id": 48, - "type": "stats_notification", - "updated_at": 1451522691 - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_alerts-alertid", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/user/profile": { - "get": { - "operationId": "GET_user-profile", - "summary": "Get a user's profile", - "tags": ["Users API"], - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "GET User Profile response", - "type": "object", - "properties": { - "address": { - "type": "string", - "description": "The user's address." - }, - "address2": { - "type": "string", - "description": "The second line of the user's address." - }, - "city": { - "type": "string", - "description": "The user's city." - }, - "company": { - "type": "string", - "description": "The name of the user's company." - }, - "country": { - "type": "string", - "description": "The user's country." - }, - "first_name": { - "type": "string", - "description": "The user's first name." - }, - "last_name": { - "type": "string", - "description": "The user's last name." - }, - "phone": { - "type": "string", - "description": "The user's phone number." - }, - "state": { - "type": "string", - "description": "The user's state." - }, - "website": { - "type": "string", - "description": "The user's website URL." - }, - "zip": { - "type": "string", - "description": "The user's zip code." - } - }, - "required": [ - "address", - "city", - "company", - "country", - "first_name", - "last_name", - "phone", - "state", - "website", - "zip" - ] - }, - "examples": { - "response": { - "value": { - "address": "814 West Chapman Avenue", - "address2": "", - "city": "Orange", - "company": "SendGrid", - "country": "US", - "first_name": "Test", - "last_name": "User", - "phone": "555-555-5555", - "state": "CA", - "website": "http://www.sendgrid.com", - "zip": "92868" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-profile", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_user-profile", - "summary": "Update a user's profile", - "tags": ["Users API"], - "description": "**This endpoint allows you to update your current profile details.**\n\nAny one or more of the parameters can be updated via the PATCH `/user/profile` endpoint. You must include at least one when you PATCH.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/user_profile" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/user_profile" - }, - "examples": { - "response": { - "value": { - "address": "814 West Chapman Avenue", - "address2": "", - "city": "Orange", - "company": "SendGrid", - "country": "US", - "first_name": "Example", - "last_name": "User", - "phone": "555-555-5555", - "state": "CA", - "website": "http://www.sendgrid.com", - "zip": "92868" - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_user-profile", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/user/account": { - "get": { - "operationId": "GET_user-account", - "summary": "Get a user's account information.", - "tags": ["Users API"], - "description": "**This endpoint allows you to retrieve your user account details.**\n\nYour user's account information includes the user's account type and reputation.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "GET User Account response", - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of account for this user.", - "enum": ["free", "paid"] - }, - "reputation": { - "type": "number", - "description": "The sender reputation for this user." - } - }, - "required": ["type", "reputation"] - }, - "examples": { - "response": { - "value": { - "reputation": 100, - "type": "paid" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-account", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/user/email": { - "get": { - "operationId": "GET_user-email", - "summary": "Retrieve your account email address", - "tags": ["Users API"], - "description": "**This endpoint allows you to retrieve the email address currently on file for your account.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address currently on file for your account.", - "format": "email" - } - }, - "required": ["email"] - }, - "examples": { - "response": { - "value": { - "email": "test@example.com" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-email", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "put": { - "operationId": "PUT_user-email", - "summary": "Update your account email address", - "tags": ["Users API"], - "description": "**This endpoint allows you to update the email address currently on file for your account.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The new email address that you would like to use for your account." - } - }, - "example": { - "email": "example@example.com" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The current email address on file for your account.", - "format": "email" - } - }, - "required": ["email"] - }, - "examples": { - "response": { - "value": { - "email": "example@example.com" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PUT_user-email", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/user/username": { - "get": { - "operationId": "GET_user-username", - "summary": "Retrieve your username", - "tags": ["Users API"], - "description": "**This endpoint allows you to retrieve your current account username.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "Your account username." - }, - "user_id": { - "type": "integer", - "description": "The user ID for your account." - } - }, - "required": ["username", "user_id"] - }, - "examples": { - "response": { - "value": { - "username": "test_username", - "user_id": 1 - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-username", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "put": { - "operationId": "PUT_user-username", - "summary": "Update your username", - "tags": ["Users API"], - "description": "**This endpoint allows you to update the username for your account.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The new username you would like to use for your account." - } - }, - "example": { - "username": "test_username" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The current username on file for your account." - } - }, - "required": ["username"] - }, - "examples": { - "response": { - "value": { - "username": "test_username" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PUT_user-username", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/user/credits": { - "get": { - "operationId": "GET_user-credits", - "summary": "Retrieve your credit balance", - "tags": ["Users API"], - "description": "**This endpoint allows you to retrieve the current credit balance for your account.**\n\nEach account has a credit balance, which is a base number of emails it can send before receiving per-email charges. For more information about credits and billing, see [Billing and Plan details information](https://sendgrid.com/docs/ui/account-and-settings/billing/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "remain": { - "type": "integer", - "description": "The remaining number of credits available on your account." - }, - "total": { - "type": "integer", - "description": "The total number of credits assigned to your account." - }, - "overage": { - "type": "integer", - "description": "The number of overdrawn credits for your account." - }, - "used": { - "type": "integer", - "description": "The number of credits that you have used." - }, - "last_reset": { - "type": "string", - "description": "The date that your credit balance was last reset." - }, - "next_reset": { - "type": "string", - "description": "The next date that your credit balance will be reset." - }, - "reset_frequency": { - "type": "string", - "description": "The frequency at which your credit balance will be reset." - } - }, - "required": [ - "remain", - "total", - "overage", - "used", - "last_reset", - "next_reset", - "reset_frequency" - ] - }, - "examples": { - "response": { - "value": { - "remain": 200, - "total": 200, - "overage": 0, - "used": 0, - "last_reset": "2013-01-01", - "next_reset": "2013-02-01", - "reset_frequency": "monthly" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-credits", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/user/password": { - "put": { - "operationId": "PUT_user-password", - "summary": "Update your password", - "tags": ["Users API"], - "description": "**This endpoint allows you to update your password.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "new_password": { - "type": "string", - "description": "The new password you would like to use for your account." - }, - "old_password": { - "type": "string", - "description": "The old password for your account." - } - }, - "required": ["new_password", "old_password"], - "example": { - "new_password": "new_password", - "old_password": "old_password" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PUT_user-password", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/subusers": { - "get": { - "operationId": "GET_subusers", - "summary": "List all Subusers", - "tags": ["Subusers API"], - "description": "**This endpoint allows you to retrieve a list of all of your subusers.**\n\nYou can choose to retrieve specific subusers as well as limit the results that come back from the API.", - "parameters": [ - { - "name": "username", - "in": "query", - "description": "The username of this subuser.", - "schema": { - "type": "string" - } - }, - { - "name": "limit", - "in": "query", - "description": "The number of results you would like to get in each request.", - "schema": { - "type": "integer" - } - }, - { - "name": "offset", - "in": "query", - "description": "The number of subusers to skip.", - "schema": { - "type": "integer" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/subuser" - } - }, - "examples": { - "response": { - "value": [ - { - "disabled": false, - "email": "example@example.com", - "id": 1234, - "username": "example_subuser" - }, - { - "disabled": false, - "email": "example2@example.com", - "id": 1234, - "username": "example_subuser2" - } - ] - } - } - } - } - }, - "401": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_subusers", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "post": { - "operationId": "POST_subusers", - "summary": "Create Subuser", - "tags": ["Subusers API"], - "description": "**This endpoint allows you to create a new subuser.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username for this subuser." - }, - "email": { - "type": "string", - "description": "The email address of the subuser.", - "format": "email" - }, - "password": { - "type": "string", - "description": "The password this subuser will use when logging into SendGrid." - }, - "ips": { - "type": "array", - "description": "The IP addresses that should be assigned to this subuser.", - "items": { - "type": "string", - "format": "ipv4" - } - } - }, - "required": ["username", "email", "password", "ips"], - "example": { - "username": "John@example.com", - "email": "John@example.com", - "password": "johns_password", - "ips": ["1.1.1.1", "2.2.2.2"] - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/subuser_post" - }, - "examples": { - "response": { - "value": { - "username": "example_subuser", - "user_id": 1234, - "email": "example@example.com", - "signup_session_token": "", - "authorization_token": "", - "credit_allocation": { - "type": "unlimited" - } - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "username exists" - }, - { - "message": "unable to validate IPs at this time" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "403": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "you dont have permission to access this resource" - } - ] - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "unable to validate IPs at this time" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_subusers", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/subusers/{subuser_name}": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "patch": { - "operationId": "PATCH_subusers-subuser_name", - "summary": "Enable/disable a subuser", - "tags": ["Subusers API"], - "description": "**This endpoint allows you to enable or disable a subuser.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "disabled": { - "type": "boolean", - "description": "Whether or not this subuser is disabled. True means disabled, False means enabled." - } - }, - "example": { - "disabled": false - } - } - } - } - }, - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "invalid username" - }, - { - "message": "no fields provided" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "unable to enable user" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_subusers-subusername", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_subusers-subuser_name", - "summary": "Delete a subuser", - "tags": ["Subusers API"], - "description": "**This endpoint allows you to delete a subuser.**\n\nThis is a permanent action. Once deleted, a subuser cannot be retrieved.", - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_subusers-subusername", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/subusers/reputations": { - "get": { - "operationId": "GET_subusers-reputations", - "summary": "Retrieve Subuser Reputations", - "tags": ["Subusers API"], - "description": "**This endpoint allows you to request the reputations for your subusers.**\n\nSubuser sender reputations give a good idea how well a sender is doing with regards to how recipients and recipient servers react to the mail that is being received. When a bounce, spam report, or other negative action happens on a sent email, it will affect your sender rating.", - "parameters": [ - { - "name": "usernames", - "in": "query", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "reputation": { - "type": "number", - "description": "The sender reputation this subuser has attained." - }, - "username": { - "type": "string", - "description": "The subuser that has this reputation.f" - } - }, - "required": ["reputation", "username"] - } - }, - "examples": { - "response": { - "value": [ - { - "username": "example_subuser", - "reputation": 99 - }, - { - "username": "example_subuser2", - "reputation": 95.2 - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_subusers-reputations", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/subusers/{subuser_name}/ips": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "put": { - "operationId": "PUT_subusers-subuser_name-ips", - "summary": "Update IPs assigned to a subuser", - "tags": ["Subusers API"], - "description": "**This endpoint allows you update your subusers' assigned IP.**\n\nEach subuser should be assigned to an IP address from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have one or more of their own IP addresses as well. \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/ui/account-and-settings/dedicated-ip-addresses/)\n* [Setup Reverse DNS](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/)", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "array", - "description": "The IP addresses you would like to assign to the subuser.", - "items": { - "type": "string", - "format": "ipv4" - }, - "example": ["127.0.0.1"] - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ips": { - "type": "array", - "description": "The IP addresses that are assigned to the subuser.", - "items": { - "type": "string", - "format": "ipv4" - } - } - } - }, - "examples": { - "response": { - "value": { - "ips": ["127.0.0.1"] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PUT_subusers-subusername-ips", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/subusers/{subuser_name}/monitor": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "description": "The name of the subuser for which to retrieve monitor settings.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_subusers-subuser_name-monitor", - "summary": "Retrieve monitor settings for a subuser", - "tags": ["Subuser Monitor Settings"], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/monitor" - }, - "examples": { - "response": { - "value": { - "email": "example@example.com", - "frequency": 500 - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "No monitor settings for this user" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_subusers-subusername-monitor", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "post": { - "operationId": "POST_subusers-subuser_name-monitor", - "summary": "Create monitor settings", - "tags": ["Subuser Monitor Settings"], - "requestBody": { - "$ref": "#/components/requestBodies/monitor" - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/monitor" - }, - "examples": { - "response": { - "value": { - "email": "example@example.com", - "frequency": 50000 - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "User already has a monitor" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_subusers-subusername-monitor", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "put": { - "operationId": "PUT_subusers-subuser_name-monitor", - "summary": "Update Monitor Settings for a subuser", - "tags": ["Subuser Monitor Settings"], - "requestBody": { - "$ref": "#/components/requestBodies/monitor" - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/monitor" - }, - "examples": { - "response": { - "value": { - "email": "example@example.com", - "frequency": 500 - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "email", - "message": "Email is required" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PUT_subusers-subusername-monitor", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_subusers-subuser_name-monitor", - "summary": "Delete monitor settings", - "tags": ["Subuser Monitor Settings"], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "No monitor settings for this user" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_subusers-subusername-monitor", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/subusers/{subuser_name}/stats/monthly": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_subusers-subuser_name-stats-monthly", - "summary": "Retrieve the monthly email statistics for a single subuser", - "tags": ["Subuser Statistics"], - "description": "**This endpoint allows you to retrive the monthly email statistics for a specific subuser.**\n\nWhen using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:\n`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.", - "parameters": [ - { - "name": "date", - "in": "query", - "description": "The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "sort_by_metric", - "in": "query", - "description": "The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.'", - "required": false, - "schema": { - "type": "string", - "default": "delivered" - } - }, - { - "name": "sort_by_direction", - "in": "query", - "description": "The direction you want to sort.", - "required": false, - "schema": { - "type": "string", - "enum": ["desc", "asc"], - "default": "desc" - } - }, - { - "name": "limit", - "in": "query", - "description": "Optional field to limit the number of results returned.", - "required": false, - "schema": { - "type": "integer", - "default": 5 - } - }, - { - "name": "offset", - "in": "query", - "description": "Optional beginning point in the list to retrieve from.", - "required": false, - "schema": { - "type": "integer", - "default": 0 - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/subuser_stats" - }, - "examples": { - "response": { - "value": { - "date": "2016-02-01", - "stats": [ - { - "first_name": "John", - "last_name": "Doe", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 5, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 10, - "processed": 10, - "requests": 10, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "user1", - "type": "subuser" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_subusers-subusername-stats-monthly", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/subusers/stats/monthly": { - "get": { - "operationId": "GET_subusers-stats-monthly", - "summary": "Retrieve monthly stats for all subusers", - "tags": ["Subuser Statistics"], - "description": "**This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.**\n\nWhen using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:\n`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.", - "parameters": [ - { - "name": "date", - "in": "query", - "description": "The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "subuser", - "in": "query", - "description": "A substring search of your subusers.", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "sort_by_metric", - "in": "query", - "description": "The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.'", - "required": false, - "schema": { - "type": "string", - "enum": [ - "blocks", - "bounces", - "clicks", - "delivered", - "opens", - "requests", - "unique_clicks", - "unique_opens", - "unsubscribes" - ], - "default": "delivered" - } - }, - { - "name": "sort_by_direction", - "in": "query", - "description": "The direction you want to sort.", - "required": false, - "schema": { - "type": "string", - "enum": ["desc", "asc"], - "default": "desc" - } - }, - { - "name": "limit", - "in": "query", - "description": "Optional field to limit the number of results returned.", - "required": false, - "schema": { - "type": "integer", - "default": 5 - } - }, - { - "name": "offset", - "in": "query", - "description": "Optional beginning point in the list to retrieve from.", - "required": false, - "schema": { - "type": "integer", - "default": 0 - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/subuser_stats" - }, - "examples": { - "response": { - "value": { - "date": "2016-02-01", - "stats": [ - { - "first_name": "John", - "last_name": "Doe", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 1, - "processed": 0, - "requests": 100, - "spam_report_drops": 0, - "spam_reports": 99, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "user1", - "type": "subuser" - }, - { - "first_name": "Jane", - "last_name": "Doe", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 5, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 10, - "processed": 10, - "requests": 10, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "user2", - "type": "subuser" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_subusers-stats-monthly", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/subusers/stats/sums": { - "get": { - "operationId": "GET_subusers-stats-sums", - "summary": "Retrieve the totals for each email statistic metric for all subusers.", - "tags": ["Subuser Statistics"], - "description": "**This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.**", - "parameters": [ - { - "name": "sort_by_direction", - "in": "query", - "description": "The direction you want to sort. ", - "required": false, - "schema": { - "type": "string", - "enum": ["desc", "asc"], - "default": "desc" - } - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "limit", - "in": "query", - "description": "Limits the number of results returned per page.", - "required": false, - "schema": { - "type": "integer", - "default": 5 - } - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list to begin retrieving results from.", - "required": false, - "schema": { - "type": "integer", - "default": 0 - } - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "sort_by_metric", - "in": "query", - "description": "The metric that you want to sort by. Must be a single metric.", - "required": false, - "schema": { - "type": "string", - "default": "delivered" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/category_stats" - }, - "examples": { - "response": { - "value": { - "date": "2015-10-11", - "stats": [] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_subusers-stats-sums", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/subusers/stats": { - "get": { - "operationId": "GET_subusers-stats", - "summary": "Retrieve email statistics for your subusers.", - "tags": ["Subuser Statistics"], - "description": "**This endpoint allows you to retrieve the email statistics for the given subusers.**\n\nYou may retrieve statistics for up to 10 different subusers by including an additional _subusers_ parameter for each additional subuser.", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Limits the number of results returned per page.", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list to begin retrieving results from.", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "schema": { - "type": "string", - "enum": ["day", "week", "month"] - } - }, - { - "name": "subusers", - "in": "query", - "description": "The subuser you want to retrieve statistics for. You may include this parameter up to 10 times to retrieve statistics for multiple subusers.", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today.", - "required": false, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/category_stats" - } - }, - "examples": { - "response": { - "value": [ - { - "date": "2015-10-01", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-02", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-03", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-04", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-05", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-06", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-07", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-08", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-09", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-10", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_subusers-stats", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/whitelabel/links": { - "post": { - "operationId": "POST_whitelabel-links", - "summary": "Create a branded link", - "tags": ["Link branding"], - "description": "**This endpoint allows you to create a new branded link.**\n\nTo create the link branding, supply the root domain and, optionally, the subdomain — these go into separate fields in your request body. The root domain should match your FROM email address. If you provide a subdomain, it must be different from the subdomain you used for authenticating your domain.\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "domain": { - "type": "string", - "description": "The root domain for the subdomain that you are creating the link branding for. This should match your FROM email address." - }, - "subdomain": { - "type": "string", - "description": "The subdomain to create the link branding for. Must be different from the subdomain you used for authenticating your domain." - }, - "default": { - "type": "boolean", - "description": "Indicates if you want to use this link branding as the default or fallback. When setting a new default, the existing default link branding will have its default status removed automatically.", - "enum": [true, false] - } - }, - "required": ["domain"], - "example": { - "domain": "example.com", - "subdomain": "mail", - "default": true - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/link_branding_200_response" - }, - "examples": { - "response": { - "value": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_whitelabel-links", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_whitelabel-links", - "summary": "Retrieve all branded links", - "tags": ["Link branding"], - "description": "**This endpoint allows you to retrieve all branded links**.\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Limits the number of results returned per page.", - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/link_branding_200_response" - } - }, - "examples": { - "response": { - "value": [ - { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": true, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - }, - { - "id": 2, - "domain": "example2.com", - "subdomain": "news", - "username": "john@example.com", - "user_id": 8, - "default": false, - "valid": false, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "news.example2.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": false, - "type": "cname", - "host": "8.example2.com", - "data": "sendgrid.net" - } - } - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_whitelabel-links", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/whitelabel/links/{id}/validate": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The ID of the branded link that you want to validate.", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "post": { - "operationId": "POST_whitelabel-links-id-validate", - "summary": "Validate a branded link", - "tags": ["Link branding"], - "description": "**This endpoint allows you to validate a branded link.**\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the branded link." - }, - "valid": { - "type": "boolean", - "description": "Indicates if the link branding is valid.", - "enum": [true, false] - }, - "validation_results": { - "type": "object", - "description": "The individual validation results for each of the DNS records associated with this branded link.", - "required": ["domain_cname"], - "properties": { - "domain_cname": { - "type": "object", - "description": "The DNS record generated for the sending domain used for this branded link.", - "required": ["valid", "reason"], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this DNS record is valid.", - "enum": [true, false] - }, - "reason": { - "type": "string", - "nullable": true, - "description": "Null if the DNS record is valid. If the DNS record is invalid, this will explain why." - } - } - }, - "owner_cname": { - "type": "object", - "description": "The DNS record created to verify the branded link.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid.", - "enum": [true, false] - }, - "reason": { - "type": "string", - "nullable": true, - "description": "Null if valid. If the DNS record is invalid, this will explain why." - } - }, - "required": ["valid", "reason"] - } - } - } - }, - "required": ["id", "valid", "validation_results"] - }, - "examples": { - "response": { - "value": { - "id": 1, - "valid": true, - "validation_results": { - "domain_cname": { - "valid": false, - "reason": "Expected CNAME to match \"sendgrid.net.\" but found \"example.com.\"." - }, - "owner_cname": { - "valid": true, - "reason": null - } - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The reasons why the validation failed.", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "The reason why the link whitelabel could not be validated." - } - }, - "required": ["message"] - } - } - }, - "required": ["errors"] - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "internal error getting CNAME" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_whitelabel-links-id-validate", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/whitelabel/links/{link_id}/subuser": { - "parameters": [ - { - "name": "link_id", - "in": "path", - "description": "The ID of the branded link you want to associate.", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "post": { - "operationId": "POST_whitelabel-links-link_id-subuser", - "summary": "Associate a branded link with a subuser", - "tags": ["Link branding"], - "description": "**This endpoint allows you to associate a branded link with a subuser account.**\n\nLink branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers).", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username of the subuser account that you want to associate the branded link with." - } - }, - "example": { - "username": "jane@example.com" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/link_branding_200_response" - }, - "examples": { - "response": { - "value": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_whitelabel-links-linkid-subuser", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/whitelabel/links/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The ID of the branded link you want to retrieve.", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "get": { - "operationId": "GET_whitelabel-links-id", - "summary": "Retrieve a branded link", - "tags": ["Link branding"], - "description": "**This endpoint allows you to retrieve a specific branded link by providing its ID.**\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/link_branding_200_response" - }, - "examples": { - "response": { - "value": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_whitelabel-links-id", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_whitelabel-links-id", - "summary": "Update a branded link", - "tags": ["Link branding"], - "description": "**This endpoint allows you to update a specific branded link. You can use this endpoint to change a branded link's default status.**\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "default": { - "type": "boolean", - "description": "Indicates if the branded link is set as the default. When setting a new default, the existing default link branding will have its default status removed automatically.", - "enum": [true, false] - } - }, - "example": { - "default": true - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/link_branding_200_response" - }, - "examples": { - "response": { - "value": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": true, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_whitelabel-links-id", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_whitelabel-links-id", - "summary": "Delete a branded link", - "tags": ["Link branding"], - "description": "**This endpoint allows you to delete a branded link.**\n\nYour request will receive a response with a 204 status code if the deletion was successful. The call does not return the link's details, so if you wish to record these make sure you call the \"Retrieve a branded link\" endpoint *before* you request its deletion.\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_whitelabel-links-id", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/whitelabel/links/default": { - "get": { - "operationId": "GET_whitelabel-links-default", - "summary": "Retrieve the default branded link", - "tags": ["Link branding"], - "description": "**This endpoint allows you to retrieve the default branded link.**\n\nThe default branded link is the actual URL to be used when sending messages. If you have more than one branded link, the default is determined by the following order:\n\n* The validated branded link marked as `default` (set when you call the \"Create a branded link\" endpoint or by calling the \"Update a branded link\" endpoint on an existing link)\n* Legacy branded links (migrated from the whitelabel wizard)\n* Default SendGrid-branded links (i.e., `100.ct.sendgrid.net`)\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", - "parameters": [ - { - "name": "domain", - "in": "query", - "description": "The domain to match against when finding the default branded link.", - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/link_branding_200_response" - }, - "examples": { - "response": { - "value": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_whitelabel-links-default", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/whitelabel/links/subuser": { - "get": { - "operationId": "GET_whitelabel-links-subuser", - "summary": "Retrieve a subuser's branded link", - "tags": ["Link branding"], - "description": "**This endpoint allows you to retrieve the branded link associated with a subuser.**\n\nLink branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and then validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers).", - "parameters": [ - { - "name": "username", - "in": "query", - "description": "The username of the subuser to retrieve associated branded links for.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/link_branding_200_response" - }, - "examples": { - "response": { - "value": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_whitelabel-links-subuser", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_whitelabel-links-subuser", - "summary": "Disassociate a branded link from a subuser", - "tags": ["Link branding"], - "description": "**This endpoint allows you to take a branded link away from a subuser.**\n\nLink branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers).\n\nYour request will receive a response with a 204 status code if the disassociation was successful.", - "parameters": [ - { - "name": "username", - "in": "query", - "description": "The username of the subuser account that you want to disassociate a branded link from.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_whitelabel-links-subuser", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/ips/warmup": { - "post": { - "operationId": "POST_ips-warmup", - "summary": "Start warming up an IP address", - "tags": ["IP Warmup"], - "description": "**This endpoint allows you to put an IP address into warmup mode.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address that you want to begin warming up." - } - }, - "example": { - "ip": "0.0.0.0" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ip_warmup_response" - }, - "examples": { - "response": { - "value": [ - { - "ip": "0.0.0.0", - "start_date": 1409616000 - } - ] - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The errors that were encountered.", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string", - "nullable": true - }, - "message": { - "type": "string", - "description": "A message explaining why the IP couldn't entered into warmup mode." - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "resource not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_ips-warmup", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_ips-warmup", - "summary": "Retrieve all IPs currently in warmup", - "tags": ["IP Warmup"], - "description": "**This endpoint allows you to retrieve all of your IP addresses that are currently warming up.**", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ip_warmup_response" - }, - "examples": { - "response": { - "value": [ - { - "ip": "0.0.0.0", - "start_date": 1409616000 - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_ips-warmup", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/ips/warmup/{ip_address}": { - "parameters": [ - { - "name": "ip_address", - "in": "path", - "description": "The IP address that you want to retrieve the warmup status for.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_ips-warmup-ip_address", - "summary": "Retrieve the warmup status for a specific IP address", - "tags": ["IP Warmup"], - "description": "**This endpoint allows you to retrieve the warmup status for a specific IP address.**\n\nYou can retrieve all of your warming IPs using the \"Retrieve all IPs currently in warmup\" endpoint.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ip_warmup_response" - }, - "examples": { - "response": { - "value": [ - { - "ip": "0.0.0.0", - "start_date": 1409616000 - } - ] - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The errors that were encountered.", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string", - "nullable": true - }, - "message": { - "type": "string", - "description": "A message explaining why the warmup status could not be retrieved." - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "resource not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_ips-warmup-ipaddress", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_ips-warmup-ip_address", - "summary": "Stop warming up an IP address", - "tags": ["IP Warmup"], - "description": "**This endpoint allows you to remove an IP address from warmup mode.**\n\nYour request will return a 204 status code if the specified IP was successfully removed from warmup mode. To retrieve details of the IP’s warmup status *before* removing it from warmup mode, call the \"Retrieve the warmpup status for a specific IP address\" endpoint.", - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The errors that were encountered.", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string", - "nullable": true - }, - "message": { - "type": "string", - "description": "A message explaining why the IP couldn't be removed from warmup." - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "resource not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_ips-warmup-ipaddress", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/whitelabel/ips": { - "post": { - "operationId": "POST_whitelabel-ips", - "summary": "Set up reverse DNS", - "tags": ["Reverse DNS"], - "description": "**This endpoint allows you to set up reverse DNS.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address for which you want to set up reverse DNS." - }, - "subdomain": { - "type": "string", - "description": "The subdomain that will be used to send emails from the IP address. This should be the same as the subdomain used to set up an authenticated domain." - }, - "domain": { - "type": "string", - "description": "The root, or sending, domain that will be used to send message from the IP address." - } - }, - "required": ["ip", "domain"], - "example": { - "ip": "192.168.1.1", - "subdomain": "email", - "domain": "example.com" - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/reverse_dns" - }, - "examples": { - "response": { - "value": { - "id": 123, - "ip": "192.168.1.2", - "rdns": "o1.email.example.com", - "users": [], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o1.email.example.com", - "data": "192.168.1.2" - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_whitelabel-ips", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_whitelabel-ips", - "summary": "Retrieve all reverse DNS records", - "tags": ["Reverse DNS"], - "description": "**This endpoint allows you to retrieve all of the Reverse DNS records created by this account.**\n\nYou may include a search key by using the `ip` query string parameter. This enables you to perform a prefix search for a given IP segment (e.g., `?ip=\"192.\"`).\n\nUse the `limit` query string parameter to reduce the number of records returned. All records will be returned if you have fewer records than the specified limit.\n\nThe `offset` query string parameter allows you to specify a non-zero index from which records will be returned. For example, if you have ten records, `?offset=5` will return the last five records (at indexes 5 through 9). The list starts at index zero.", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The maximum number of results to retrieve.", - "schema": { - "type": "integer" - } - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list of results to begin retrieving IP addresses from.", - "schema": { - "type": "integer" - } - }, - { - "name": "ip", - "in": "query", - "description": "The IP address segment that you'd like to use in a prefix search.", - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/reverse_dns" - } - }, - "examples": { - "response": { - "value": [ - { - "id": 1, - "ip": "192.168.1.1", - "rdns": "o1.email.example.com", - "users": [ - { - "username": "john@example.com", - "user_id": 7 - }, - { - "username": "jane@example.com", - "user_id": 8 - } - ], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o1.email.example.com", - "data": "192.168.1.1" - } - }, - { - "id": 2, - "ip": "192.168.1.2", - "rdns": "o2.email.example.com", - "users": [ - { - "username": "john@example.com", - "user_id": 7 - }, - { - "username": "jane@example2.com", - "user_id": 9 - } - ], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o2.email.example.com", - "data": "192.168.1.2" - } - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_whitelabel-ips", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/whitelabel/ips/{id}/validate": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The ID of the reverse DNS record that you would like to validate.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "post": { - "operationId": "POST_whitelabel-ips-id-validate", - "summary": "Validate a reverse DNS record", - "tags": ["Reverse DNS"], - "description": "**This endpoint allows you to validate a reverse DNS record.**\n\nAlways check the `valid` property of the response’s `validation_results.a_record` object. This field will indicate whether it was possible to validate the reverse DNS record. If the `validation_results.a_record.valid` is `false`, this indicates only that Twilio SendGrid could not determine the validity your reverse DNS record — it may still be valid.\n\nIf validity couldn’t be determined, you can check the value of `validation_results.a_record.reason` to find out why.\n\nYou can retrieve the IDs associated with all your reverse DNS records using the \"Retrieve all reverse DNS records\" endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the reverse DNS record." - }, - "valid": { - "type": "boolean", - "description": "Indicates if the reverse DNS record is valid.", - "enum": [true, false] - }, - "validation_results": { - "type": "object", - "description": "The specific results of the validation.", - "properties": { - "a_record": { - "type": "object", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the reverse DNS record could be validated.", - "enum": [true, false] - }, - "reason": { - "description": "The reason the reverse DNS record could not be validated. Is `null` if the reverse DNS record was validated.", - "nullable": true, - "type": "string" - } - }, - "required": ["valid", "reason"] - } - } - } - }, - "required": ["id", "valid", "validation_results"] - }, - "examples": { - "response": { - "value": { - "id": 123456, - "valid": false, - "validation_results": { - "a_record": { - "valid": false, - "reason": "Failed to resolve A Record at o1.ptr4283.example.com: lookup o1.ptr4283.example.com on 192.168.0.10:53: no such host" - } - } - } - } - } - } - } - }, - "404": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The error messages for the failed validation.", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "A message describing why the reverse DNS could not be validated." - } - }, - "required": ["message"] - } - } - }, - "required": ["errors"] - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "Reverse DNS record not found." - } - ] - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The error messages for the failed validation.", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "A message describing why the IP whitelabel could not be validated." - } - }, - "required": ["message"] - } - } - }, - "required": ["errors"] - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "internal error getting rDNS" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_whitelabel-ips-id-validate", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/whitelabel/ips/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The ID of the reverse DNS record that you would like to retrieve.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_whitelabel-ips-id", - "summary": "Retrieve a reverse DNS record", - "tags": ["Reverse DNS"], - "description": "**This endpoint allows you to retrieve a reverse DNS record.**\n\nYou can retrieve the IDs associated with all your reverse DNS records using the \"Retrieve all reverse DNS records\" endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/reverse_dns" - }, - "examples": { - "response": { - "value": { - "id": 123, - "ip": "192.168.1.1", - "rdns": "o1.email.example.com", - "users": [ - { - "username": "john@example.com", - "user_id": 7 - } - ], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o1.email.example.com", - "data": "192.168.1.1" - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_whitelabel-ips-id", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_whitelabel-ips-id", - "summary": "Delete a reverse DNS record", - "tags": ["Reverse DNS"], - "description": "**This endpoint allows you to delete a reverse DNS record.**\n\nA call to this endpoint will respond with a 204 status code if the deletion was successful.\n\nYou can retrieve the IDs associated with all your reverse DNS records using the \"Retrieve all reverse DNS records\" endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_whitelabel-ips-id", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/validations/email": { - "post": { - "operationId": "POST_validations-email", - "summary": "Validate an email", - "tags": ["Email Address Validation"], - "description": "**This endpoint allows you to validate an email address.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address that you want to validate." - }, - "source": { - "type": "string", - "description": "A one-word classifier for where this validation originated." - } - }, - "required": ["email"], - "example": { - "email": "example@example.com", - "source": "signup" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "object", - "required": [ - "email", - "verdict", - "score", - "local", - "host", - "checks", - "ip_address" - ], - "properties": { - "email": { - "type": "string", - "description": "The email being validated", - "format": "email" - }, - "verdict": { - "type": "string", - "description": "A generic classification of whether or not the email address is valid.", - "enum": ["Valid", "Risky", "Invalid"] - }, - "score": { - "type": "number", - "description": "A numeric representation of the email validity." - }, - "local": { - "type": "string", - "description": "The local part of the email address." - }, - "host": { - "type": "string", - "description": "The domain of the email address.", - "format": "hostname" - }, - "suggestion": { - "type": "string", - "description": "A suggested correction in the event of domain name typos (e.g., gmial.com)" - }, - "checks": { - "type": "object", - "description": "Granular checks for email address validity.", - "required": ["domain", "local_part", "additional"], - "properties": { - "domain": { - "type": "object", - "description": "Checks on the domain portion of the email address.", - "required": [ - "has_valid_address_syntax", - "has_mx_or_a_record", - "is_suspected_disposable_address" - ], - "properties": { - "has_valid_address_syntax": { - "type": "boolean", - "description": "Whether the email address syntax is valid." - }, - "has_mx_or_a_record": { - "type": "boolean", - "description": "Whether the email has appropriate DNS records to deliver a message. " - }, - "is_suspected_disposable_address": { - "type": "boolean", - "description": "Whether the domain appears to be from a disposable email address service." - } - } - }, - "local_part": { - "type": "object", - "description": "Checks on the local part of the email address.", - "required": ["is_suspected_role_address"], - "properties": { - "is_suspected_role_address": { - "type": "boolean", - "description": "Whether the local part of email appears to be a role or group (e.g., hr, admin)" - } - } - }, - "additional": { - "type": "object", - "description": "Additional checks on the email address.", - "required": ["has_known_bounces", "has_suspected_bounces"], - "properties": { - "has_known_bounces": { - "type": "boolean", - "description": "WHether email sent to this address from your account has bounced." - }, - "has_suspected_bounces": { - "type": "boolean", - "description": "Whether our model predicts that the email address might bounce." - } - } - } - } - }, - "source": { - "type": "string", - "description": "The source of the validation, as per the API request." - }, - "ip_address": { - "type": "string", - "description": "The IP address associated with this email." - } - } - } - }, - "required": ["result"] - }, - "examples": { - "response": { - "value": { - "result": { - "email": "cedric@fogowl.com", - "verdict": "Valid", - "score": 0.85021, - "local": "cedric", - "host": "fogowl.com", - "checks": { - "domain": { - "has_valid_address_syntax": true, - "has_mx_or_a_record": true, - "is_suspected_disposable_address": false - }, - "local_part": { - "is_suspected_role_address": false - }, - "additional": { - "has_known_bounces": false, - "has_suspected_bounces": false - } - }, - "ip_address": "192.168.1.1" - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_validations-email", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/whitelabel/dns/email": { - "post": { - "operationId": "POST_whitelabel-dns-email", - "summary": "Email DNS records to a co-worker", - "tags": ["Email CNAME records"], - "description": "**This endpoint is used to share DNS records with a colleagues**\n\nUse this endpoint to send SendGrid-generated DNS record information to a co-worker so they can enter it into your DNS provider to validate your domain and link branding. \n\nWhat type of records are sent will depend on whether you have chosen Automated Security or not. When using Automated Security, SendGrid provides you with three CNAME records. If you turn Automated Security off, you are instead given TXT and MX records.\n\nIf you pass a `link_id` to this endpoint, the generated email will supply the DNS records necessary to complete [Link Branding](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/) setup. If you pass a `domain_id` to this endpoint, the generated email will supply the DNS records needed to complete [Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/). Passing both IDs will generate an email with the records needed to complete both setup steps.\n\nYou can retrieve all your domain IDs from the returned `id` fields for each domain using the \"List all authenticated domains\" endpoint. You can retrieve all of your link IDs using the \"Retrieve all branded links\" endpoint.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "link_id": { - "type": "integer", - "minimum": 0, - "description": "The ID of the branded link." - }, - "domain_id": { - "type": "integer", - "minimum": 0, - "description": "The ID of your SendGrid domain record." - }, - "email": { - "type": "string", - "format": "email", - "description": "The email address to send the DNS information to." - }, - "message": { - "type": "string", - "default": "Please set these DNS records in our hosting solution.", - "description": "A custom text block to include in the email body sent with the records." - } - }, - "required": ["link_id", "domain_id", "email"], - "example": { - "link_id": 29719392, - "domain_id": 46873408, - "email": "my_colleague@example.com", - "message": "DNS Record for verification" - } - } - } - } - }, - "responses": { - "204": { - "description": "" - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "object", - "properties": { - "error": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_whitelabel-dns-email", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/ips/pools": { - "post": { - "operationId": "POST_ips-pools", - "summary": "Create an IP pool", - "tags": ["IP Pools"], - "description": "**This endpoint allows you to create an IP pool.**\n\nBefore you can create an IP pool, you need to activate the IP in your SendGrid account: \n\n1. Log into your SendGrid account. \n1. Navigate to **Settings** and then select **IP Addresses**. \n1. Find the IP address you want to activate and then click **Edit**. \n1. Check **Allow my account to send mail using this IP address**.\n1. Click **Save**.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of your new IP pool.", - "maxLength": 64 - } - }, - "required": ["name"], - "example": { - "name": "marketing" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ip_pool_response" - }, - "examples": { - "response": { - "value": { - "name": "marketing" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_ips-pools", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_ips-pools", - "summary": "Retrieve all IP pools", - "tags": ["IP Pools"], - "description": "**This endpoint allows you to get all of your IP pools.**", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ip_pool_response" - } - }, - "examples": { - "response": { - "value": [ - { - "name": "marketing" - }, - { - "name": "transactional" - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_ips-pools", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 200 - } - } - } - }, - "/ips/pools/{pool_name}/ips": { - "parameters": [ - { - "name": "pool_name", - "in": "path", - "description": "The name of the IP pool you want to add the address to. If the name contains spaces, they must be URL encoded (e.g., \"Test Pool\" becomes \"Test%20Pool\").", - "required": true, - "schema": { - "type": "string" - } - } - ], - "post": { - "operationId": "POST_ips-pools-pool_name-ips", - "summary": "Add an IP address to a pool", - "tags": ["IP Pools"], - "description": "**This endpoint allows you to add an IP address to an IP pool.**\n\nYou can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made.\n\nBefore you can add an IP to a pool, you need to activate it in your SendGrid account:\n\n1. Log into your SendGrid account. \n1. Navigate to **Settings** and then select **IP Addresses**. \n1. Find the IP address you want to activate and then click **Edit**. \n1. Check **Allow my account to send mail using this IP address**.\n1. Click **Save**.\n\nYou can retrieve all of your available IP addresses from the \"Retrieve all IP addresses\" endpoint.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address that you want to add to the named pool." - } - }, - "example": { - "ip": "0.0.0.0" - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address." - }, - "pools": { - "type": "array", - "description": "The IP pools that this IP address has been added to.", - "items": { - "type": "string" - } - }, - "start_date": { - "type": "integer", - "description": "A Unix timestamp indicating when the warmup process began for the added IP address." - }, - "warmup": { - "type": "boolean", - "description": "Indicates if the IP address is in warmup." - } - }, - "required": ["ip", "pools", "start_date", "warmup"] - }, - "examples": { - "response": { - "value": { - "ip": "000.00.00.0", - "pools": ["test1"], - "start_date": 1409616000, - "warmup": true - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The error returned.", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string", - "nullable": true - }, - "message": { - "type": "string", - "description": "A message explaining why the IP address could not be added to the IP Pool." - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "resource not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_ips-pools-poolname-ips", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/ips/pools/{pool_name}": { - "parameters": [ - { - "name": "pool_name", - "in": "path", - "description": "The name of the IP pool that you want to retrieve the IP addresses for.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_ips-pools-pool_name", - "summary": "Retrieve all the IPs in a specified pool", - "tags": ["IP Pools"], - "description": "**This endpoint allows you to get all of the IP addresses that are in a specific IP pool.**", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "pool_name": { - "type": "string", - "description": "The name of the IP pool.", - "maxLength": 64 - }, - "ips": { - "description": "The IP addresses that belong to this pool.", - "type": "array", - "items": { - "type": "string" - } - } - } - }, - "examples": { - "response": { - "value": { - "pool_name": "Sample", - "ips": ["192.168.1.1", "192.158.1.2", "192.138.2.1"] - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string", - "description": "The name of the error." - }, - "message": { - "type": "string", - "description": "A message explaining why the IP addresses could not be listed." - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "error", - "message": "Unable to locate specified IPs Pool" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_ips-pools-poolname", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "put": { - "operationId": "PUT_ips-pools-pool_name", - "summary": "Rename an IP pool", - "tags": ["IP Pools"], - "description": "**This endpoint allows you to update the name of an IP pool.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The new name for your IP pool.", - "maxLength": 64 - } - }, - "example": { - "name": "new_pool_name" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ip_pool_response" - }, - "examples": { - "response": { - "value": { - "name": "new_pool_name" - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string", - "nullable": true - }, - "message": { - "type": "string", - "description": "A message explaining why the name of your IP pool could not be updated." - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "ip pool not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PUT_ips-pools-poolname", - "public": true, - "mock": { - "statusCode": 200, - "dynamic": false, - "enabled": false - } - } - }, - "delete": { - "operationId": "DELETE_ips-pools-pool_name", - "summary": "Delete an IP pool", - "tags": ["IP Pools"], - "description": "**This endpoint allows you to delete an IP pool.**", - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "error": { - "type": "string", - "description": "An error explaining why the pool could not be deleted." - } - } - }, - "examples": { - "response": { - "value": { - "error": "Unable to locate specified IPs Pool" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_ips-pools-poolname", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/ips/pools/{pool_name}/ips/{ip}": { - "parameters": [ - { - "name": "pool_name", - "in": "path", - "description": "The name of the IP pool that you are removing the IP address from.", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "ip", - "in": "path", - "description": "The IP address that you wish to remove.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "delete": { - "operationId": "DELETE_ips-pools-pool_name-ips-ip", - "summary": "Remove an IP address from a pool", - "tags": ["IP Pools"], - "description": "**This endpoint allows you to remove an IP address from an IP pool.**", - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "error": { - "type": "string", - "description": "An error explaining why the IP address could not be removed from the IP pool." - } - } - }, - "examples": { - "response": { - "value": { - "error": "Unable to locate specified IPs Pool" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_ips-pools-poolname-ips-ip", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/ips": { - "post": { - "operationId": "POST_ips", - "summary": "Add IPs", - "tags": ["IP Addresses"], - "description": "**This endpoint is for adding a(n) IP Address(es) to your account.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "count": { - "type": "integer", - "description": "The amount of IPs to add to the account." - }, - "subusers": { - "type": "array", - "description": "Array of usernames to be assigned a send IP.", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean", - "default": false, - "description": "Whether or not to warmup the IPs being added." - } - }, - "required": ["count"], - "example": { - "count": 90323478, - "subusers": ["subuser1", "subuser2"], - "warmup": true, - "user_can_send": true - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ips": { - "type": "array", - "description": "List of IP objects.", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "IP added to account." - }, - "subusers": { - "type": "array", - "description": "Array of usernames assigned a send IP.", - "items": { - "type": "string" - } - } - }, - "required": ["ip", "subusers"] - } - }, - "remaining_ips": { - "type": "integer", - "description": "The number of IPs that can still be added to the user." - }, - "warmup": { - "type": "boolean", - "description": "Whether or not the IPs are being warmed up." - } - }, - "required": ["ips", "remaining_ips", "warmup"] - }, - "examples": { - "response": { - "value": { - "ips": [ - { - "ip": "1.2.3.4", - "subusers": ["user", "subuser1"] - }, - { - "ip": "1.2.3.5", - "subusers": ["user", "subuser1"] - } - ], - "remaining_ips": 1, - "warmup": true - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "one or more subusers do not belong to this user" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_ips", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_ips", - "summary": "Retrieve all IP addresses", - "tags": ["IP Addresses"], - "description": "**This endpoint allows you to retrieve a list of all assigned and unassigned IPs.**\n\nResponse includes warm up status, pools, assigned subusers, and reverse DNS info. The start_date field corresponds to when warmup started for that IP.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", - "parameters": [ - { - "name": "ip", - "in": "query", - "description": "The IP address to get", - "schema": { - "type": "string" - } - }, - { - "name": "exclude_whitelabels", - "in": "query", - "description": "Should we exclude reverse DNS records (whitelabels)?", - "schema": { - "type": "boolean" - } - }, - { - "name": "limit", - "in": "query", - "description": "The number of IPs you want returned at the same time.", - "schema": { - "type": "integer", - "default": 10 - } - }, - { - "name": "offset", - "in": "query", - "description": "The offset for the number of IPs that you are requesting.", - "schema": { - "type": "integer", - "default": 0 - } - }, - { - "name": "subuser", - "in": "query", - "description": "The subuser you are requesting for.", - "schema": { - "type": "string" - } - }, - { - "name": "sort_by_direction", - "in": "query", - "description": "The direction to sort the results.", - "schema": { - "type": "string", - "enum": ["desc", "asc"] - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "An IP address." - }, - "subusers": { - "type": "array", - "description": "The subusers that are able to send email from this IP.", - "items": { - "type": "string" - } - }, - "rdns": { - "type": "string", - "description": "The reverse DNS record for this IP address." - }, - "pools": { - "type": "array", - "description": "The IP pools that this IP has been added to.", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean", - "description": "Indicates if this IP address is currently warming up." - }, - "start_date": { - "description": "The date that the IP address was entered into warmup.", - "nullable": true, - "type": "number" - }, - "whitelabeled": { - "type": "boolean", - "description": "Indicates if this IP address is associated with a reverse DNS record." - }, - "assigned_at": { - "description": "The date that the IP address was assigned to the user.", - "nullable": true, - "type": "integer" - } - }, - "required": [ - "ip", - "subusers", - "pools", - "warmup", - "start_date", - "whitelabeled", - "assigned_at" - ] - } - }, - "examples": { - "response": { - "value": [ - { - "ip": "192.168.1.1", - "pools": ["pool1", "pool2"], - "whitelabeled": false, - "start_date": 1409616000, - "subusers": ["tim@sendgrid.net"], - "warmup": false, - "assigned_at": 1482883200 - }, - { - "ip": "208.115.214.22", - "pools": [], - "whitelabeled": true, - "rdns": "o1.email.burgermail.com", - "start_date": 1409616000, - "subusers": [], - "warmup": false, - "assigned_at": 1482883200 - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_ips", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/ips/remaining": { - "get": { - "operationId": "GET_ips-remaining", - "summary": "Get remaining IPs count", - "tags": ["IP Addresses"], - "description": "**This endpoint gets amount of IP Addresses that can still be created during a given period and the price of those IPs.**", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "results": { - "type": "array", - "items": { - "type": "object", - "properties": { - "remaining": { - "type": "integer", - "description": "The number of IPs that can still be added to the user." - }, - "period": { - "type": "string", - "description": "The length of time until user can add more IPs." - }, - "price_per_ip": { - "type": "number", - "description": "The current cost to add an IP." - } - }, - "required": ["remaining", "period", "price_per_ip"] - } - } - }, - "required": ["results"] - }, - "examples": { - "response": { - "value": { - "results": [ - { - "remaining": 2, - "period": "month", - "price_per_ip": 20 - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_ips-remaining", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/ips/assigned": { - "get": { - "operationId": "GET_ips-assigned", - "summary": "Retrieve all assigned IPs", - "tags": ["IP Addresses"], - "description": "**This endpoint allows you to retrieve only assigned IP addresses.**\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "title": "List all assigned IPs response", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address." - }, - "pools": { - "type": "array", - "description": "The IP pools that this IP address has been added to.", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean", - "description": "Indicates if this IP address is currently warming up." - }, - "start_date": { - "type": "integer", - "description": "The start date that this IP address was entered into warmup." - } - }, - "required": ["ip", "pools", "warmup", "start_date"] - } - }, - "examples": { - "response": { - "value": [ - { - "ip": "167.89.21.3", - "pools": ["new_test5"], - "warmup": true, - "start_date": 1409616000 - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_ips-assigned", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/ips/{ip_address}": { - "parameters": [ - { - "name": "ip_address", - "in": "path", - "description": "The IP address you are retrieving the IP pools for.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_ips-ip_address", - "summary": "Retrieve all IP pools an IP address belongs to", - "tags": ["IP Addresses"], - "description": "**This endpoint allows you to see which IP pools a particular IP address has been added to.**\n\nThe same IP address can be added to multiple IP pools.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address." - }, - "subusers": { - "type": "array", - "description": "The subusers that can send email using this IP address.", - "items": { - "type": "string" - } - }, - "rdns": { - "type": "string", - "description": "The reverse DNS record for this IP address." - }, - "pools": { - "type": "array", - "description": "The list of IP pools that this IP address belongs to.", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean", - "description": "Indicates if this IP address is currently warming up." - }, - "start_date": { - "description": "The date that the IP address was entered into warmup.", - "nullable": true, - "type": "integer" - }, - "whitelabeled": { - "type": "boolean", - "description": "Indicates if this IP address is associated with a reverse DNS record." - } - }, - "required": [ - "ip", - "subusers", - "rdns", - "pools", - "warmup", - "start_date", - "whitelabeled" - ] - }, - "examples": { - "response": { - "value": { - "ip": "000.00.00.0", - "subusers": ["subuser1", "subuser2"], - "rdns": "o1.em.example.com", - "pools": ["test1"], - "warmup": false, - "start_date": null, - "whitelabeled": true - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_ips-ipaddress", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 200 - } - } - } - }, - "/whitelabel/domains": { - "get": { - "operationId": "GET_whitelabel-domains", - "summary": "List all authenticated domains", - "tags": ["Domain Authentication"], - "description": "**This endpoint allows you to retrieve a list of all domains you have authenticated.**", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Number of domains to return.", - "schema": { - "type": "integer" - } - }, - { - "name": "offset", - "in": "query", - "description": "Paging offset.", - "schema": { - "type": "integer" - } - }, - { - "name": "exclude_subusers", - "in": "query", - "description": "Exclude subuser domains from the result.", - "schema": { - "type": "boolean" - } - }, - { - "name": "username", - "in": "query", - "description": "The username associated with an authenticated domain.", - "schema": { - "type": "string" - } - }, - { - "name": "domain", - "in": "query", - "description": "Search for authenticated domains.", - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/domain-authentication-200-response" - }, - "examples": { - "response": { - "value": [ - { - "id": 1, - "user_id": 7, - "subdomain": "mail", - "domain": "example.com", - "username": "jane@example.com", - "ips": ["192.168.1.1", "192.168.1.2"], - "custom_spf": true, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": true, - "dns": { - "mail_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "u7.wl.sendgrid.net" - }, - "dkim1": { - "valid": true, - "type": "cname", - "host": "s1._domainkey.example.com", - "data": "s1._domainkey.u7.wl.sendgrid.net" - }, - "dkim2": { - "valid": true, - "type": "cname", - "host": "s2._domainkey.example.com", - "data": "s2._domainkey.u7.wl.sendgrid.net" - } - } - }, - { - "id": 2, - "user_id": 8, - "subdomain": "new", - "domain": "example2.com", - "username": "john@example2.com", - "ips": [], - "custom_spf": false, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": false, - "dns": { - "mail_cname": { - "valid": false, - "type": "mx", - "host": "news.example2.com", - "data": "sendgrid.net" - }, - "dkim1": { - "valid": false, - "type": "txt", - "host": "example2.com", - "data": "k=rsa; t=s; p=publicKey" - }, - "dkim2": { - "valid": false, - "type": "txt", - "host": "example2.com", - "data": "k=rsa; t=s p=publicKey" - } - } - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_whitelabel-domains", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "post": { - "operationId": "POST_whitelabel-domains", - "summary": "Authenticate a domain", - "tags": ["Domain Authentication"], - "description": "**This endpoint allows you to authenticate a domain.**\n\nIf you are authenticating a domain for a subuser, you have two options:\n1. Use the \"username\" parameter. This allows you to authenticate a domain on behalf of your subuser. This means the subuser is able to see and modify the authenticated domain.\n2. Use the Association workflow (see Associate Domain section). This allows you to authenticate a domain created by the parent to a subuser. This means the subuser will default to the assigned domain, but will not be able to see or modify that authenticated domain. However, if the subuser authenticates their own domain it will overwrite the assigned domain.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "domain": { - "type": "string", - "description": "Domain being authenticated." - }, - "subdomain": { - "type": "string", - "description": "The subdomain to use for this authenticated domain." - }, - "username": { - "type": "string", - "description": "The username associated with this domain." - }, - "ips": { - "type": "array", - "description": "The IP addresses that will be included in the custom SPF record for this authenticated domain.", - "items": { - "type": "string" - } - }, - "custom_spf": { - "type": "boolean", - "description": "Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to authenticated domains set up for manual security." - }, - "default": { - "type": "boolean", - "description": "Whether to use this authenticated domain as the fallback if no authenticated domains match the sender's domain." - }, - "automatic_security": { - "type": "boolean", - "description": "Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation." - }, - "custom_dkim_selector": { - "type": "string", - "description": "Add a custom DKIM selector. Accepts three letters or numbers." - } - }, - "required": ["domain"], - "example": { - "domain": "example.com", - "subdomain": "news", - "username": "john@example.com", - "ips": ["192.168.1.1", "192.168.1.2"], - "custom_spf": true, - "default": true, - "automatic_security": false - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/authentication_domain" - }, - "examples": { - "response": { - "value": { - "id": 302183, - "user_id": 1446226, - "subdomain": "example", - "domain": "example.com", - "username": "mbernier", - "ips": [], - "custom_spf": false, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": false, - "dns": { - "mail_cname": { - "valid": false, - "type": "cname", - "host": "example.example.com", - "data": "u1446226.wl.sendgrid.net" - }, - "dkim1": { - "valid": false, - "type": "cname", - "host": "s1._domainkey.example.com", - "data": "s1.domainkey.u1446226.wl.sendgrid.net" - }, - "dkim2": { - "valid": false, - "type": "cname", - "host": "s2._domainkey.example.com", - "data": "s2.domainkey.u1446226.wl.sendgrid.net" - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_whitelabel-domains", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/whitelabel/domains/{domain_id}": { - "parameters": [ - { - "name": "domain_id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_whitelabel-domains-domain_id", - "summary": "Retrieve an authenticated domain", - "tags": ["Domain Authentication"], - "description": "**This endpoint allows you to retrieve a specific authenticated domain.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/authentication_domain" - }, - "examples": { - "response": { - "value": { - "id": 45373692, - "user_id": 66036447, - "subdomain": "sub", - "domain": "example.com", - "username": "jdoe", - "ips": ["127.0.0.1"], - "custom_spf": false, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": true, - "dns": { - "mail_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "u7.wl.sendgrid.net" - }, - "dkim1": { - "valid": true, - "type": "cname", - "host": "s1._domainkey.example.com", - "data": "s1._domainkey.u7.wl.sendgrid.net" - }, - "dkim2": { - "valid": true, - "type": "cname", - "host": "s2._domainkey.example.com", - "data": "s2._domainkey.u7.wl.sendgrid.net" - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_whitelabel-domains-domainid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_whitelabel-domains-domain_id", - "summary": "Update an authenticated domain", - "tags": ["Domain Authentication"], - "description": "**This endpoint allows you to update the settings for an authenticated domain.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "default": { - "type": "boolean", - "default": false, - "description": "Indicates whether this is the default authenticated domain." - }, - "custom_spf": { - "type": "boolean", - "default": false, - "description": "Indicates whether to generate a custom SPF record for manual security." - } - }, - "example": { - "default": false, - "custom_spf": true - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/domain-authentication-200-response" - }, - "examples": { - "response": { - "value": [ - { - "id": 1, - "user_id": 7, - "subdomain": "mail", - "domain": "example.com", - "username": "jane@example.com", - "ips": ["192.168.1.1", "192.168.1.2"], - "custom_spf": true, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": true, - "dns": { - "mail_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "u7.wl.sendgrid.net" - }, - "dkim1": { - "valid": true, - "type": "cname", - "host": "s1._domainkey.example.com", - "data": "s1._domainkey.u7.wl.sendgrid.net" - }, - "dkim2": { - "valid": true, - "type": "cname", - "host": "s2._domainkey.example.com", - "data": "s2._domainkey.u7.wl.sendgrid.net" - } - } - }, - { - "id": 2, - "user_id": 8, - "subdomain": "new", - "domain": "example2.com", - "username": "john@example2.com", - "ips": [], - "custom_spf": false, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": false, - "dns": { - "mail_cname": { - "valid": false, - "type": "mx", - "host": "news.example2.com", - "data": "sendgrid.net" - }, - "dkim1": { - "valid": false, - "type": "txt", - "host": "example2.com", - "data": "k=rsa; t=s; p=publicKey" - }, - "dkim2": { - "valid": false, - "type": "txt", - "host": "example2.com", - "data": "k=rsa; t=s p=publicKey" - } - } - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_whitelabel-domains-domainid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_whitelabel-domains-domain_id", - "summary": "Delete an authenticated domain.", - "tags": ["Domain Authentication"], - "description": "**This endpoint allows you to delete an authenticated domain.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_whitelabel-domains-domainid", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/whitelabel/domains/default": { - "get": { - "operationId": "GET_whitelabel-domains-default", - "summary": "Get the default authentication", - "tags": ["Domain Authentication"], - "description": "**This endpoint allows you to retrieve the default authentication for a domain.**\n\nWhen creating or updating a domain authentication, you can set the domain as a default. The default domain will be used to send all mail. If you have multiple authenticated domains, the authenticated domain matching the domain of the From address will be used, and the default will be overridden.\n\nThis endpoint will return a default domain and its details only if a default is set. You are not required to set a default. If you do not set a default domain, this endpoint will return general information about your domain authentication status.", - "parameters": [ - { - "name": "domain", - "in": "query", - "description": "The domain to find a default authentication.", - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/domain-authentication-200-response" - }, - "examples": { - "response": { - "value": [ - { - "id": 1, - "user_id": 7, - "subdomain": "mail", - "domain": "example.com", - "username": "jane@example.com", - "ips": ["192.168.1.1", "192.168.1.2"], - "custom_spf": true, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": true, - "dns": { - "mail_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "u7.wl.sendgrid.net" - }, - "dkim1": { - "valid": true, - "type": "cname", - "host": "s1._domainkey.example.com", - "data": "s1._domainkey.u7.wl.sendgrid.net" - }, - "dkim2": { - "valid": true, - "type": "cname", - "host": "s2._domainkey.example.com", - "data": "s2._domainkey.u7.wl.sendgrid.net" - } - } - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_whitelabel-domains-default", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/whitelabel/domains/{id}/ips": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of the domain to which you are adding an IP", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "post": { - "operationId": "POST_whitelabel-domains-id-ips", - "summary": "Add an IP to an authenticated domain", - "tags": ["Domain Authentication"], - "description": "**This endpoint allows you to add an IP address to an authenticated domain.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "IP to associate with the domain. Used for manually specifying IPs for custom SPF." - } - }, - "required": ["ip"], - "example": { - "ip": "192.168.0.1" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/domain_authentication_domain_spf" - }, - "examples": { - "response": { - "value": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "ips": [], - "custom_spf": true, - "default": false, - "legacy": false, - "automatic_security": false, - "valid": false, - "dns": { - "mail_server": { - "host": "mail.example.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false - }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false - }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_whitelabel-domains-id-ips", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/whitelabel/domains/{id}/ips/{ip}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of the domain to delete the IP from.", - "required": true, - "schema": { - "type": "integer" - } - }, - { - "name": "ip", - "in": "path", - "description": "IP to remove from the domain.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "delete": { - "operationId": "DELETE_whitelabel-domains-id-ips-ip", - "summary": "Remove an IP from an authenticated domain.", - "tags": ["Domain Authentication"], - "description": "**This endpoint allows you to remove an IP address from that domain's authentication.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/domain_authentication_domain_spf" - }, - "examples": { - "response": { - "value": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "mail@example.com", - "user_id": 7, - "ips": [], - "custom_spf": true, - "default": false, - "legacy": false, - "automatic_security": false, - "valid": false, - "dns": { - "mail_server": { - "host": "mail.example.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false - }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false - }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_whitelabel-domains-id-ips-ip", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/whitelabel/domains/{id}/validate": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of the domain to validate.", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "post": { - "operationId": "POST_whitelabel-domains-id-validate", - "summary": "Validate a domain authentication.", - "tags": ["Domain Authentication"], - "description": "**This endpoint allows you to validate an authenticated domain. If it fails, it will return an error message describing why the domain could not be validated.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the authenticated domain." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid authenticated domain." - }, - "validation_results": { - "type": "object", - "description": "The individual DNS records that are checked when validating, including the reason for any invalid DNS records.", - "properties": { - "mail_cname": { - "type": "object", - "description": "The CNAME record for the authenticated domain.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this DNS record is valid." - }, - "reason": { - "description": "The reason this record is invalid.", - "nullable": true, - "type": "string" - } - } - }, - "dkim1": { - "type": "object", - "description": "A DNS record for this authenticated domain.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid." - }, - "reason": { - "nullable": true, - "type": "string" - } - } - }, - "dkim2": { - "type": "object", - "description": "A DNS record for this authenticated domain.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid." - }, - "reason": { - "nullable": true, - "type": "string" - } - } - }, - "spf": { - "type": "object", - "description": "The SPF record for the authenticated domain.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the SPF record is valid." - }, - "reason": { - "nullable": true, - "type": "string" - } - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "id": 1, - "valid": true, - "validation_resuts": { - "mail_cname": { - "valid": false, - "reason": "Expected your MX record to be \"mx.sendgrid.net\" but found \"example.com\"." - }, - "dkim1": { - "valid": true, - "reason": null - }, - "dkim2": { - "valid": true, - "reason": null - }, - "spf": { - "valid": true, - "reason": null - } - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "A message explaining the reason for the error." - } - }, - "required": ["message"] - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "internal error getting TXT" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_whitelabel-domains-id-validate", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/whitelabel/domains/subuser": { - "get": { - "operationId": "GET_whitelabel-domains-subuser", - "summary": "List the authenticated domain associated with the given user.", - "tags": ["Domain Authentication"], - "description": "**This endpoint allows you to retrieve all of the authenticated domains that have been assigned to a specific subuser.**\n\nAuthenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate an authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The parent may then associate the authenticated domain via the subuser management tools.", - "parameters": [ - { - "name": "username", - "in": "query", - "description": "Username for the subuser to find associated authenticated domain.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/domain_authentication_domain_spf" - }, - "examples": { - "response": { - "value": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "mail@example.com", - "user_id": 7, - "ips": [], - "custom_spf": true, - "default": false, - "legacy": false, - "automatic_security": false, - "valid": false, - "dns": { - "mail_server": { - "host": "mail.example.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false - }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false - }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_whitelabel-domains-subuser", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_whitelabel-domains-subuser", - "summary": "Disassociate an authenticated domain from a given user.", - "tags": ["Domain Authentication"], - "description": "**This endpoint allows you to disassociate a specific authenticated domain from a subuser.**\n\nAuthenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate an authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The parent may then associate the authenticated domain via the subuser management tools.", - "parameters": [ - { - "name": "username", - "in": "query", - "description": "Username for the subuser to find associated authenticated domain.", - "schema": { - "type": "string" - } - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_whitelabel-domains-subuser", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/whitelabel/domains/{domain_id}/subuser": { - "parameters": [ - { - "name": "domain_id", - "in": "path", - "description": "ID of the authenticated domain to associate with the subuser", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "post": { - "operationId": "POST_whitelabel-domains-domain_id-subuser", - "summary": "Associate an authenticated domain with a given user.", - "tags": ["Domain Authentication"], - "description": "**This endpoint allows you to associate a specific authenticated domain with a subuser.**\n\nAuthenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate an authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The parent may then associate the authenticated domain via the subuser management tools.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "Username to associate with the authenticated domain." - } - }, - "required": ["username"], - "example": { - "username": "jdoe" - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/domain_authentication_domain_spf" - }, - "examples": { - "response": { - "value": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "mail@example.com", - "user_id": 7, - "ips": [], - "custom_spf": true, - "default": false, - "legacy": false, - "automatic_security": false, - "valid": false, - "dns": { - "mail_server": { - "host": "mail.example.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false - }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false - }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_whitelabel-domains-domainid-subuser", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/verified_senders/domains": { - "get": { - "operationId": "GET_verified_senders-domains", - "summary": "Domain Warn List", - "tags": ["Sender Verification"], - "description": "**This endpoint returns a list of domains known to implement DMARC and categorizes them by failure type — hard failure or soft failure**.\n\nDomains listed as hard failures will not deliver mail when used as a [Sender Identity](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/) due to the domain's DMARC policy settings.\n\nFor example, using a `yahoo.com` email address as a Sender Identity will likely result in the rejection of your mail. For more information about DMARC, see [Everything about DMARC](https://sendgrid.com/docs/ui/sending-email/dmarc/).", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "results": { - "type": "object", - "required": ["soft_failures", "hard_failures"], - "properties": { - "soft_failures": { - "type": "array", - "items": { - "type": "string" - } - }, - "hard_failures": { - "type": "array", - "items": { - "type": "string" - } - } - } - } - }, - "required": ["results"] - }, - "examples": { - "response": { - "value": { - "results": { - "soft_failures": ["gmail.com"], - "hard_failures": ["yahoo.com"] - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_verifiedsenders-domains", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/verified_senders/steps_completed": { - "get": { - "operationId": "GET_verified_senders-steps_completed", - "summary": "Completed Steps", - "tags": ["Sender Verification"], - "description": "**This endpoint allows you to determine which of SendGrid’s verification processes have been completed for an account**.\n\nThis endpoint returns boolean values, `true` and `false`, for [Domain Authentication](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/#domain-authentication), `domain_verified`, and [Single Sender Verification](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/#single-sender-verification), `sender_verified`, for the account.\n\nAn account may have one, both, or neither verification steps completed. If you need to authenticate a domain rather than a Single Sender, see the \"Authenticate a domain\" endpoint.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "results": { - "type": "object", - "properties": { - "sender_verified": { - "type": "boolean" - }, - "domain_verified": { - "type": "boolean" - } - } - } - } - }, - "examples": { - "response": { - "value": { - "results": { - "domain_verified": true, - "sender_verified": true - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_verifiedsenders-stepscompleted", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/verified_senders": { - "post": { - "operationId": "POST_verified_senders", - "summary": "Create Verified Sender Request", - "tags": ["Sender Verification"], - "description": "**This endpoint allows you to create a new Sender Identify**.\n\nUpon successful submission of a `POST` request to this endpoint, an identity will be created, and a verification email will be sent to the address assigned to the `from_email` field. You must complete the verification process using the sent email to fully verify the sender.\n\nIf you need to resend the verification email, you can do so with the Resend Verified Sender Request, `/resend/{id}`, endpoint.\n\nIf you need to authenticate a domain rather than a Single Sender, see the [Domain Authentication API](https://sendgrid.api-docs.io/v3.0/domain-authentication/authenticate-a-domain).", - "requestBody": { - "$ref": "#/components/requestBodies/verified-sender-request-schema" - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/verified-sender-response-schema" - }, - "examples": { - "response": { - "value": { - "id": 1234, - "nickname": "Example Orders", - "from_email": "orders@example.com", - "from_name": "Example Orders", - "reply_to": "orders@example.com", - "reply_to_name": "Example Orders", - "address": "1234 Fake St.", - "address2": "PO Box 1234", - "state": "CA", - "city": "San Francisco", - "country": "USA", - "zip": "94105", - "verified": true, - "locked": false - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - }, - "required": ["message", "error_id"] - } - } - }, - "required": ["errors"] - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_verifiedsenders", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_verified_senders", - "summary": "Get All Verified Senders", - "tags": ["Sender Verification"], - "description": "**This endpoint allows you to retrieve all the Sender Identities associated with an account.**\n\nThis endpoint will return both verified and unverified senders.\n\nYou can limit the number of results returned using the `limit`, `lastSeenID`, and `id` query string parameters.\n\n* `limit` allows you to specify an exact number of Sender Identities to return.\n* `lastSeenID` will return senders with an ID number occuring after the passed in ID. In other words, the `lastSeenID` provides a starting point from which SendGrid will iterate to find Sender Identities associated with your account.\n* `id` will return information about only the Sender Identity passed in the request.", - "parameters": [ - { - "name": "limit", - "in": "query", - "schema": { - "type": "number" - } - }, - { - "name": "lastSeenID", - "in": "query", - "schema": { - "type": "number" - } - }, - { - "name": "id", - "in": "query", - "schema": { - "type": "integer" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/verified-sender-response-schema" - } - } - } - }, - "examples": { - "response": { - "value": { - "results": [ - { - "id": 1234, - "nickname": "Example Orders", - "from_email": "orders@example.com", - "from_name": "Example Orders", - "reply_to": "orders@example.com", - "reply_to_name": "Example Orders", - "address": "1234 Fake St.", - "address2": "PO Box 1234", - "state": "CA", - "city": "San Francisco", - "country": "USA", - "zip": "94105", - "verified": true, - "locked": false - }, - { - "id": 1235, - "nickname": "Example Support", - "from_email": "support@example.com", - "from_name": "Example Support", - "reply_to": "support@example.com", - "reply_to_name": "Example Support", - "address": "1234 Fake St.", - "address2": "PO Box 1234", - "state": "CA", - "city": "San Francisco", - "country": "USA", - "zip": "94105", - "verified": true, - "locked": false - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_verifiedsenders", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/verified_senders/verify/{token}": { - "parameters": [ - { - "name": "token", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_verified_senders-verify-token", - "summary": "Verify Sender Request", - "tags": ["Sender Verification"], - "description": "**This endpoint allows you to verify a sender requests.**\n\nThe token is generated by SendGrid and included in a verification email delivered to the address that's pending verification.", - "responses": { - "204": { - "description": "" - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - }, - "required": ["message", "error_id"] - } - } - }, - "required": ["errors"] - } - } - } - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_verifiedsenders-verify-token", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/verified_senders/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "patch": { - "operationId": "PATCH_verified_senders-id", - "summary": "Edit Verified Sender", - "tags": ["Sender Verification"], - "description": "**This endpoint allows you to update an existing Sender Identity**.\n\nPass the `id` assigned to a Sender Identity to this endpoint as a path parameter. Include any fields you wish to update in the request body in JSON format.\n\nYou can retrieve the IDs associated with Sender Identities by passing a `GET` request to the Get All Verified Senders endpoint, `/verified_senders`.\n\n**Note:** Unlike a `PUT` request, `PATCH` allows you to update only the fields you wish to edit. Fields that are not passed as part of a request will remain unaltered.", - "requestBody": { - "$ref": "#/components/requestBodies/verified-sender-request-schema" - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/verified-sender-response-schema" - }, - "examples": { - "response": { - "value": { - "id": 1234, - "nickname": "Example Orders", - "from_email": "orders@example.com", - "from_name": "Example Orders", - "reply_to": "orders@example.com", - "reply_to_name": "Example Orders", - "address": "1234 Fake St.", - "address2": "PO Box 1234", - "state": "CA", - "city": "San Francisco", - "country": "USA", - "zip": "94105", - "verified": true, - "locked": false - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - }, - "required": ["message", "error_id"] - } - } - }, - "required": ["errors"] - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - }, - "required": ["message", "error_id"] - } - } - }, - "required": ["errors"] - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - }, - "required": ["message", "error_id"] - } - } - }, - "required": ["errors"] - } - } - } - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_verifiedsenders-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_verified_senders-id", - "summary": "Delete Verified Sender", - "tags": ["Sender Verification"], - "description": "**This endpoint allows you to delete a Sender Identity**.\n\nPass the `id` assigned to a Sender Identity to this endpoint to delete the Sender Identity from your account.\n\nYou can retrieve the IDs associated with Sender Identities using the \"Get All Verified Senders\" endpoint.", - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - }, - "required": ["message", "error_id"] - } - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - }, - "required": ["message", "error_id"] - } - } - }, - "required": ["errors"] - } - } - } - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_verifiedsenders-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/verified_senders/resend/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "post": { - "operationId": "POST_verified_senders-resend-id", - "summary": "Resend Verified Sender Request", - "tags": ["Sender Verification"], - "description": "**This endpoint allows you to resend a verification email to a specified Sender Identity**.\n\nPassing the `id` assigned to a Sender Identity to this endpoint will resend a verification email to the `from_address` associated with the Sender Identity. This can be useful if someone loses their verification email or needs to have it resent for any other reason.\n\nYou can retrieve the IDs associated with Sender Identities by passing a \"Get All Verified Senders\" endpoint.", - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - }, - "required": ["message", "error_id"] - } - } - }, - "required": ["errors"] - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - }, - "required": ["message", "error_id"] - } - } - }, - "required": ["errors"] - } - } - } - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_verifiedsenders-resend-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/designs/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The ID of the Design you want to duplicate.", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "post": { - "operationId": "POST-design-dup", - "summary": "Duplicate Design", - "tags": ["Designs API"], - "description": "**This endpoint allows you to duplicate one of your existing designs**.\n\nModifying an existing design is often the easiest way to create something new.\n\nYou are not required to pass any data in the body of a request to this endpoint. If you choose to leave the `name` field blank, your duplicate will be assigned the name of the design it was copied from with the text \"Duplicate: \" prepended to it. This name change is only a convenience, as the duplicate will be assigned a unique ID that differentiates it from your other designs.\n\nYou can modify your duplicate’s name at the time of creation by passing an updated value to the `name` field when making the initial request.\nMore on retrieving design IDs can be found below.", - "requestBody": { - "$ref": "#/components/requestBodies/design-duplicate-input" - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/design-output" - }, - "examples": { - "response": { - "value": { - "id": "15b85720-ce48-48ef-8a07-672b0d3455da", - "name": "Ahoy, Cake or Pie Cafe!", - "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", - "plain_content": "Ahoy, World!\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )", - "generate_plain_content": false, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/79bb769ae6464960a307040120ad6f9921896fe9825e845ad1f24d12285ea068.png", - "subject": "Getting Started", - "created_at": "2021-04-30T19:00:16Z", - "updated_at": "2021-04-30T19:00:16Z", - "editor": "design", - "categories": [] - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-error" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-errors" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST-design", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET-design", - "summary": "Get Design", - "tags": ["Designs API"], - "description": "**This endpoint allows you to retrieve a single design**.\n\nA GET request to `/designs/{id}` will retrieve details about a specific design in your Design Library.\n\nThis endpoint is valuable when retrieving information stored in a field that you wish to update using a PATCH request.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/design-output" - }, - "examples": { - "response": { - "value": { - "id": "15b85720-ce48-48ef-8a07-672b0d3455da", - "name": "Ahoy, World!", - "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", - "plain_content": "Ahoy, World!\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )", - "generate_plain_content": false, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/5yysvuyi1lpdnxo1ym8ax8yd7ompve3azjtme76gamdace01vko3eyn1kzso1lhy.png", - "subject": "Getting Started", - "created_at": "2021-04-30T18:51:20Z", - "updated_at": "2021-04-30T18:51:20Z", - "editor": "design", - "categories": [] - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-errors" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-errors" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET-design", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PUT-design", - "summary": "Update Design", - "tags": ["Designs API"], - "description": "**This endpoint allows you to edit a design**.\n\nThe Design API supports PATCH requests, which allow you to make partial updates to a single design. Passing data to a specific field will update only the data stored in that field; all other fields will be unaltered.\n\nFor example, updating a design's name requires that you make a PATCH request to this endpoint with data specified for the `name` field only.\n\n```\n{\n \"name\": \"\"\n}\n```", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the Design.", - "maxLength": 100, - "default": "My Design" - }, - "html_content": { - "type": "string", - "description": "The HTML content of the Design.", - "maxLength": 1048576 - }, - "plain_content": { - "type": "string", - "description": "Plain text content of the Design.", - "maxLength": 1048576, - "default": "" - }, - "generate_plain_content": { - "type": "boolean", - "description": "If true, plain_content is always generated from html_content. If false, plain_content is not altered.", - "default": true - }, - "subject": { - "type": "string", - "description": "Subject of the Design.", - "maxLength": 5000 - }, - "categories": { - "type": "array", - "description": "The list of categories applied to the design", - "uniqueItems": true, - "maxItems": 10, - "items": { - "type": "string", - "maxLength": 255 - } - } - }, - "example": { - "name": "Ahoy, World!", - "subject": "Getting Started", - "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", - "generate_plain_content": false, - "categories": ["promotions"] - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/design-output" - }, - "examples": { - "response": { - "value": { - "id": "15b85720-ce48-48ef-8a07-672b0d3455da", - "name": "Ahoy, World!", - "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", - "generate_plain_content": false, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/5yysvuyi1lpdnxo1ym8ax8yd7ompve3azjtme76gamdace01vko3eyn1kzso1lhy.png", - "subject": "Getting Started", - "created_at": "2021-04-30T18:51:20Z", - "updated_at": "2021-04-30T18:51:20Z", - "editor": "design", - "categories": ["promotions"] - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-errors" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-errors" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PUT-design", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE-design", - "summary": "Delete Design", - "tags": ["Designs API"], - "description": "**This endpoint allows you to delete a single design**.\n\nBe sure to check the ID of the design you intend to delete before making this request; deleting a design is a permanent action.", - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-errors" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-errors" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE-design", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/designs": { - "post": { - "operationId": "POST-design", - "summary": "Create Design", - "tags": ["Designs API"], - "description": "**This endpoint allows you to create a new design**.\n\nYou can add a new design by passing data, including a string of HTML email content, to `/designs`. When creating designs from scratch, be aware of the styling constraints inherent to many email clients. For a list of best practices, see our guide to [Cross-Platform Email Design](https://sendgrid.com/docs/ui/sending-email/cross-platform-html-design/).\n\nThe Design Library can also convert your design’s HTML elements into drag and drop modules that are editable in the Designs Library user interface. For more, visit the [Design and Code Editor documentation](https://sendgrid.com/docs/ui/sending-email/editor/#drag--drop-markup).\n\nBecause the `/designs` endpoint makes it easy to add designs, you can create a design with your preferred tooling or migrate designs you already own without relying on the Design Library UI.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/design-input" - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/design-output" - }, - "examples": { - "response": { - "value": { - "id": "3247eaea-c912-42a3-b0bc-60bdaf210396", - "name": "Ahoy, World!", - "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", - "plain_content": "Ahoy, World!\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )", - "generate_plain_content": false, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/kjlrmded0qnrscv8zqr39npoimrpdwgiax59q8iq6ovj7yoks2fzxoxpfjpwph6o.png", - "subject": "Getting Started", - "created_at": "2021-04-30T18:51:20Z", - "updated_at": "2021-04-30T18:51:20Z", - "editor": "design", - "categories": [] - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-errors" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST-design", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "LIST-designs", - "summary": "List Designs", - "tags": ["Designs API"], - "description": "**This endpoint allows you to retrieve a list of designs already stored in your Design Library**.\n\nA GET request to `/designs` will return a list of your existing designs. This endpoint will not return the pre-built Twilio SendGrid designs. Pre-built designs can be retrieved using the `/designs/pre-builts` endpoint, which is detailed below.\n\nBy default, you will receive 100 results per request; however, you can modify the number of results returned by passing an integer to the `page_size` query parameter.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_designsQueryStrings_page_size" - }, - { - "$ref": "#/components/parameters/trait_designsQueryStrings_page_token" - }, - { - "$ref": "#/components/parameters/trait_designsQueryStrings_summary" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/components/schemas/design-output-summary" - } - }, - "_metadata": { - "$ref": "#/components/schemas/_metadata" - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "id": "3247eaea-c912-42a3-b0bc-60bdaf210396", - "name": "Welcome Email", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/llny8o5b3m636z92p7hbjnmq1jvpka39p370jwtin2s1wxv7x1sgm0y5fk518d0s.png", - "subject": "Welcom to the Cake or Pie Cafe", - "created_at": "2021-04-09T17:29:46Z", - "updated_at": "2021-04-09T17:29:55Z", - "editor": "code", - "categories": ["welcome", "new customer"] - }, - { - "id": "02dfd792-f31f-439a-a79e-5c47fbcfdbac", - "name": "Monthly Promo", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/hfyxahd7ues2ajuoeoqq2xe6ibdasl1q89ox0y9ncya2ftpoicssmtf9ddus4c39.png", - "subject": "Free Dozen Cupcakes", - "created_at": "2021-04-09T17:29:21Z", - "updated_at": "2021-04-09T17:29:42Z", - "editor": "design", - "categories": ["promo", "coupon"] - }, - { - "id": "e54be823-19ef-4c6f-8b60-efd7514f492d", - "name": "Duplicate: Ingrid & Anders", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/12kni9gjpyb9uxmwr9vk7unycjr70u95zoyhe9sg2zounul2zg7dih1s20k13q2z.png", - "subject": "Welcome to Ingrid & Anders!", - "created_at": "2020-10-09T17:33:46Z", - "updated_at": "2021-04-07T19:57:52Z", - "editor": "design", - "categories": [] - } - ], - "_metadata": { - "self": "https://api.sendgrid.com/v3/designs?page_token=vHdvHCg0w1F-TmWJcPNpTEnFY2aPEmRBHONwOgZ6TgJbX2_I", - "count": 3 - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "LIST-designs", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/designs/pre-builts/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The ID of the pre-built Design you want to duplicate.", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "post": { - "operationId": "POST-sendgrid-pre-built-design", - "summary": "Duplicate SendGrid Pre-built Design", - "tags": ["Designs API"], - "description": "**This endpoint allows you to duplicate one of the pre-built Twilio SendGrid designs**.\n\nLike duplicating one of your existing designs, you are not required to pass any data in the body of a request to this endpoint. If you choose to leave the `name` field blank, your duplicate will be assigned the name of the design it was copied from with the text \"Duplicate: \" prepended to it. This name change is only a convenience, as the duplicate design will be assigned a unique ID that differentiates it from your other designs. You can retrieve the IDs for Twilio SendGrid pre-built designs using the \"List SendGrid Pre-built Designs\" endpoint.\n\nYou can modify your duplicate’s name at the time of creation by passing an updated value to the `name` field when making the initial request.\nMore on retrieving design IDs can be found above.", - "requestBody": { - "$ref": "#/components/requestBodies/design-duplicate-input" - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/design-output" - }, - "examples": { - "response": { - "value": { - "id": "abe0877f-a224-21e2-b62e-c789d326cda5", - "name": "Ahoy, Pre-built Design!", - "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

You've found the secret!

\n
\n \n \n \n
\"Off
\n \n \n \n
\"\"
\n \n \n \n
Welcome to the family!
\n \n \n \n
You've found a community of travelers that are just like you.
\n
 
\n
We don't want to be stuck in tourist traps that isolate us from vibrant, local experiences. We want to discover the hidden gems and less-traveled roads of our next destination.
\n
 
\n
Ready for your next authentic travel experience?
Browse Gallery
\n \n \n \n
\"\"
\n \n \n \n
\n
\n \n \n \n
\n \n \n \n \n
\n
\n \n \n \n
\n
\n \n \n \n \n \n
\n \n \n
\n \n \"Facebook\"\n \n \n \n \"Twitter\"\n \n \n \n \"Instagram\"\n \n \n \n \"Pinterest\"\n \n
\n

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", - "plain_content": "You've found the secret!\n\nWelcome to the family!\n\nYou've found a community of travelers that are just like you.\n\nWe don't want to be stuck in tourist traps that isolate us from vibrant, local experiences. We want to discover the hidden gems and less-traveled roads of our next destination.\n\nReady for your next authentic travel experience?\n\nBrowse Gallery\n\n( https://www.facebook.com/sendgrid/ ) ( https://twitter.com/sendgrid?ref_src=twsrc%5egoogle%7ctwcamp%5eserp%7ctwgr%5eauthor ) ( https://www.instagram.com/sendgrid/?hl=en ) ( https://www.pinterest.com/sendgrid/ )\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/a85b4b202ff28094828f11ff472360caecf67ead2d186b69b45c904b9251aa0b.png", - "subject": "Welcome to the family!", - "created_at": "2021-04-30T19:15:28Z", - "updated_at": "2021-04-30T19:15:28Z", - "editor": "design", - "categories": [] - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-errors" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-errors" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST-sendgrid-pre-built-design", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET-sendgrid-pre-built-design", - "summary": "Get SendGrid Pre-built Design", - "tags": ["Designs API"], - "description": "**This endpoint allows you to retrieve a single pre-built design**.\n\nA GET request to `/designs/pre-builts/{id}` will retrieve details about a specific pre-built design.\n\nThis endpoint is valuable when retrieving details about a pre-built design that you wish to duplicate and modify.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/design-output" - }, - "examples": { - "response": { - "value": { - "id": "6ad69134-7165-48cb-964a-6c3cf03e8af8", - "name": "Off Grid Adventures", - "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

You've found the secret!

\n
\n \n \n \n
\"Off
\n \n \n \n
\"\"
\n \n \n \n
Welcome to the family!
\n \n \n \n
You've found a community of travelers that are just like you.
\n
 
\n
We don't want to be stuck in tourist traps that isolate us from vibrant, local experiences. We want to discover the hidden gems and less-traveled roads of our next destination.
\n
 
\n
Ready for your next authentic travel experience?
Browse Gallery
\n \n \n \n
\"\"
\n \n \n \n
\n
\n \n \n \n
\n \n \n \n \n
\n
\n \n \n \n
\n
\n \n \n \n \n \n
\n \n \n
\n \n \"Facebook\"\n \n \n \n \"Twitter\"\n \n \n \n \"Instagram\"\n \n \n \n \"Pinterest\"\n \n
\n

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", - "plain_content": "You've found the secret!\n\nWelcome to the family!\n\nYou've found a community of travelers that are just like you.\n\nWe don't want to be stuck in tourist traps that isolate us from vibrant, local experiences. We want to discover the hidden gems and less-traveled roads of our next destination.\n\nReady for your next authentic travel experience?\n\nBrowse Gallery\n\n( https://www.facebook.com/sendgrid/ ) ( https://twitter.com/sendgrid?ref_src=twsrc%5egoogle%7ctwcamp%5eserp%7ctwgr%5eauthor ) ( https://www.instagram.com/sendgrid/?hl=en ) ( https://www.pinterest.com/sendgrid/ )\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/a85b4b202ff28094828f11ff472360caecf67ead2d186b69b45c904b9251aa0b.png", - "subject": "Welcome to the family!", - "created_at": "2019-09-10T02:11:34Z", - "updated_at": "2021-01-11T21:47:52Z", - "editor": "design", - "categories": [] - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-errors" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/api-errors" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET-sendgrid-pre-built-design", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/designs/pre-builts": { - "get": { - "operationId": "LIST-Sendgrid-Pre-built-designs", - "summary": "List SendGrid Pre-built Designs", - "tags": ["Designs API"], - "description": "**This endpoint allows you to retrieve a list of pre-built designs provided by Twilio SendGrid**.\n\nUnlike the `/designs` endpoint where *your* designs are stored, a GET request made to `designs/pre-builts` will retrieve a list of the pre-built Twilio SendGrid designs. This endpoint will not return the designs stored in your Design Library.\n\nBy default, you will receive 100 results per request; however, you can modify the number of results returned by passing an integer to the `page_size` query parameter.\n\nThis endpoint is useful for retrieving the IDs of Twilio SendGrid designs that you want to duplicate and modify.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_designsQueryStrings_page_size" - }, - { - "$ref": "#/components/parameters/trait_designsQueryStrings_page_token" - }, - { - "$ref": "#/components/parameters/trait_designsQueryStrings_summary" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/components/schemas/design-output-summary" - } - }, - "_metadata": { - "$ref": "#/components/schemas/_metadata" - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "id": "6ad69134-7165-48cb-964a-6c3cf03e8af8", - "name": "Off Grid Adventures", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/a85b4b202ff28094828f11ff472360caecf67ead2d186b69b45c904b9251aa0b.png", - "subject": "Welcome to the family!", - "created_at": "2019-09-10T02:11:34Z", - "updated_at": "2021-01-11T21:47:52Z", - "editor": "design", - "categories": [] - }, - { - "id": "b0a9c6f7-a9a1-4b52-b0c5-16fc6f4cdb2b", - "name": "Song Riddle", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/4ef3a39249f3accb8461b03950c071454a745a232508feca89a626b3e7f578d3.png", - "subject": "Welcome to Song Riddle!", - "created_at": "2019-09-10T02:12:32Z", - "updated_at": "2021-01-11T21:46:43Z", - "editor": "design", - "categories": [] - }, - { - "id": "f8d8da76-bcca-4cfe-b809-733887855f57", - "name": "Ingrid & Anders 1", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/15c97ffa97ee31693581a67526728d096eef00adfbaa34bb030d91034d477da4.png", - "subject": "Welcome to Ingrid & Anders!", - "created_at": "2019-09-10T02:10:38Z", - "updated_at": "2021-01-11T21:45:05Z", - "editor": "design", - "categories": [] - }, - { - "id": "2935a7d0-7f02-4e0f-a570-dc302ce09749", - "name": "Ingrid & Anders 2", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/7b36a6c0955cab0c350d105114ad248700a685bd11032592cdef85ae26540afc.png", - "subject": "Check out these exclusive deals!", - "created_at": "2019-09-10T02:09:31Z", - "updated_at": "2021-01-11T21:44:08Z", - "editor": "design", - "categories": [] - }, - { - "id": "7826ef14-7ba6-4dbc-91f0-a8c610ebe962", - "name": "Ingrid & Anders 3", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/6dd8dd73a1a62bd7a76c4313b52d7c749250d49e31b19cce718906655fcbc675.png", - "subject": "Join our VIP club and save big!", - "created_at": "2019-09-10T02:08:29Z", - "updated_at": "2021-01-11T21:41:35Z", - "editor": "design", - "categories": [] - }, - { - "id": "41da47e7-d3e2-491b-a83f-f499a4139d6a", - "name": "Mercado", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/9cc87cc7671719712d9d363184995d0ec05103355db300ff03641fe9e205651d.png", - "subject": "Subject", - "created_at": "2019-09-10T02:03:06Z", - "updated_at": "2021-01-11T21:39:23Z", - "editor": "design", - "categories": [] - } - ], - "_metadata": { - "self": "https://api.sendgrid.com/v3/designs/pre-builts?page_token=yYzyCxj-iIVgP54t6NjKkunDCKYLLpngo-5vAsfYXz0To34U", - "count": 6 - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "LIST-Sendgrid-Pre-built-designs", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/contacts": { - "put": { - "operationId": "PUT_mc-contacts", - "summary": "Add or Update a Contact", - "tags": ["Contacts"], - "description": "**This endpoint allows the [upsert](https://en.wiktionary.org/wiki/upsert) (insert or update) of up to 30,000 contacts, or 6MB of data, whichever is lower**. \n\nBecause the creation and update of contacts is an asynchronous process, the response will not contain immediate feedback on the processing of your upserted contacts. Rather, it will contain an HTTP 202 response indicating the contacts are queued for processing or an HTTP 4XX error containing validation errors. Should you wish to get the resulting contact's ID or confirm your contacts have been updated or added, you can use the \"Get Contacts by Emails\" endpoint. \n\nPlease note that custom fields need to have been already created if you wish to set their values for the contacts being upserted. To do this, please use the \"Create Custom Field Definition\" endpoint.\n\nYou will see a `job_id` in the response to your request. This can be used to check the status of your upsert job. To do so, please use the \"Import Contacts Status\" endpoint.\n\nIf the contact already exists in the system, any entries submitted via this endpoint will update the existing contact. The contact to update will be determined only by the `email` field and any fields omitted from the request will remain as they were. A contact's ID cannot be used to update the contact.\n\nThe email field will be changed to all lower-case. If a contact is added with an email that exists but contains capital letters, the existing contact with the all lower-case email will be updated.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "list_ids": { - "type": "array", - "description": "An array of List ID strings that this contact will be added to.", - "items": { - "type": "string", - "format": "uuid" - } - }, - "contacts": { - "type": "array", - "description": "One or more contacts objects that you intend to upsert. The available fields for a contact, including the required `email` field are described below.", - "minItems": 1, - "maxItems": 30000, - "items": { - "$ref": "#/components/schemas/contact-request" - } - } - }, - "required": ["contacts"] - } - } - } - }, - "responses": { - "202": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "job_id": { - "type": "string", - "description": "Indicates that the contacts are queued for processing. Check the job status with the \"Import Contacts Status\" endpoint." - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/error" - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PUT_mc-contacts", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_mc-contacts", - "summary": "Delete Contacts", - "tags": ["Contacts"], - "description": "**This endpoint can be used to delete one or more contacts**.\n\nThe query parameter `ids` must set to a comma-separated list of contact IDs for bulk contact deletion.\n\nThe query parameter `delete_all_contacts` must be set to `\"true\"` to delete **all** contacts. \n\nYou must set either `ids` or `delete_all_contacts`.\n\nDeletion jobs are processed asynchronously.\n\nTwilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.", - "parameters": [ - { - "name": "delete_all_contacts", - "in": "query", - "description": "Must be set to `\"true\"` to delete all contacts.", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "ids", - "in": "query", - "description": "A comma-separated list of contact IDs.", - "required": false, - "schema": { - "type": "string" - } - } - ], - "responses": { - "202": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "The deletion job has been accepted and is being processed.", - "properties": { - "job_id": { - "type": "object", - "description": "The deletion job ID." - } - }, - "required": ["job_id"] - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object" - } - } - }, - "required": ["errors"] - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_mc-contacts", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_mc-contats", - "summary": "Get Sample Contacts", - "tags": ["Contacts"], - "description": "**This endpoint will return up to 50 of the most recent contacts uploaded or attached to a list**. \n\nThis list will then be sorted by email address.\n\nThe full contact count is also returned.\n\nPlease note that pagination of the contacts has been deprecated.\n\nTwilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/components/schemas/contact-details3" - } - }, - "_metadata": { - "$ref": "#/components/schemas/selfmetadata" - }, - "contact_count": { - "type": "integer" - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/error" - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mc-contats", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/contacts/count": { - "get": { - "operationId": "GET_mc-contacts-count", - "summary": "Get Total Contact Count", - "tags": ["Contacts"], - "description": "**This endpoint returns the total number of contacts you have stored.**\n\n\nTwilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "contact_count": { - "type": "integer", - "description": "The total number of contacts." - }, - "billable_count": { - "type": "integer", - "default": 0, - "description": "The count of contacts this month for billing purposes.", - "minimum": 0 - }, - "billable_breakdown": { - "type": "object", - "description": "`billable_breakdown` will only appear to the parent user in an account with subusers.", - "properties": { - "total": { - "type": "integer", - "description": "The sum of all the subuser's billable contacts" - }, - "breakdown": { - "type": "object", - "description": "A map of each subuser's billable contact usage. Each key is the subuser's ID and each value is the usage thus far this month.", - "minProperties": 0 - } - } - } - }, - "required": ["contact_count"] - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mc-contacts-count", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/contacts/exports": { - "post": { - "operationId": "POST_mc-contacts-exports", - "summary": "Export Contacts", - "tags": ["Contacts"], - "description": "**Use this endpoint to export lists or segments of contacts**.\n\nIf you would just like to have a link to the exported list sent to your email set the `notifications.email` option to `true` in the `POST` payload.\n\nIf you would like to download the list, take the `id` that is returned and use the \"Export Contacts Status\" endpoint to get the `urls`. Once you have the list of URLs, make a `GET` request to each URL provided to download your CSV file(s).\n\nYou specify the segements and or/contact lists you wish to export by providing the relevant IDs in, respectively, the `segment_ids` and `list_ids` fields in the request body.\n\nThe lists will be provided in either JSON or CSV files. To specify which of these you would required, set the request body `file_type` field to `json` or `csv`.\n\nYou can also specify a maximum file size (in MB). If the export file is larger than this, it will be split into multiple files.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "list_ids": { - "description": "IDs of the contact lists you want to export.", - "type": "array", - "items": { - "type": "string", - "format": "uuid" - } - }, - "segment_ids": { - "description": "IDs of the contact segments you want to export.", - "type": "array", - "items": { - "type": "string" - } - }, - "notifications": { - "type": "object", - "properties": { - "email": { - "type": "boolean" - } - } - }, - "file_type": { - "type": "string", - "enum": ["csv", "json"], - "description": "File type for export file. Choose from `json` or `csv`.", - "default": "csv" - }, - "max_file_size": { - "description": "The maximum size of an export file in MB. Note that when this option is specified, multiple output files may be returned from the export.", - "default": 5000, - "type": "integer" - } - } - } - } - } - }, - "responses": { - "202": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "_metadata": { - "$ref": "#/components/schemas/metadata" - }, - "id": { - "type": "string", - "description": "The ID of the export job." - } - }, - "required": ["_metadata"] - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/error" - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_mc-contacts-exports", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_marketing-contacts-exports", - "summary": "Get All Existing Exports", - "tags": ["Contacts"], - "description": "**Use this endpoint to retrieve details of all current exported jobs**.\n\nIt will return an array of objects, each of which records an export job in flight or recently completed. \n\nEach object's `export_type` field will tell you which kind of export it is and its `status` field will indicate what stage of processing it has reached. Exports which are `ready` will be accompanied by a `urls` field which lists the URLs of the export's downloadable files — there will be more than one if you specified a maximum file size in your initial export request.\n\nUse this endpoint if you have exports in flight but do not know their IDs, which are required for the \"Export Contacts Status\" endpoint.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Export jobs ID." - }, - "status": { - "type": "string", - "description": "Allowed values: `pending`, `ready`, or `failure`." - }, - "created_at": { - "type": "string", - "description": "This ISO8601 timestamp when the export was created." - }, - "completed_at": { - "type": "string", - "description": "This ISO8601 timestamp when the export was completed." - }, - "expires_at": { - "type": "string", - "description": "This ISO8601 timestamp when the export expires." - }, - "urls": { - "type": "array", - "description": "One or more download URLs for the contact file(s) if the status is `ready`.", - "items": { - "type": "string" - } - }, - "user_id": { - "type": "string", - "description": "User ID." - }, - "export_type": { - "type": "string", - "description": "Allowed types: `contacts_export`, `list_export`, or `segment_export`." - }, - "segments": { - "type": "array", - "items": { - "type": "object", - "properties": { - "ID": { - "type": "string" - }, - "Name": { - "type": "string" - } - } - } - }, - "lists": { - "type": "array", - "items": { - "type": "object", - "properties": { - "ID": { - "type": "string" - }, - "Name": { - "type": "string" - } - } - } - }, - "_metadata": { - "type": "object", - "properties": { - "prev": { - "type": "string" - }, - "self": { - "type": "string" - }, - "next": { - "type": "string" - } - } - } - } - } - }, - "_metadata": { - "type": "object", - "properties": { - "prev": { - "type": "string" - }, - "self": { - "type": "string", - "description": "Link to this page." - }, - "next": { - "type": "string", - "description": "Link to next page." - } - } - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "": { - "type": "string" - }, - "error_id": { - "type": "string" - } - }, - "required": ["message"] - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_marketing-contacts-exports", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/contacts/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_mc-contacts-id", - "summary": "Get a Contact by ID", - "tags": ["Contacts"], - "description": "**This endpoint returns the full details and all fields for the specified contact**.\n\nThe \"Get Contacts by Emails\" endpoint can be used to get the ID of a contact.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contact-details3" - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "description": "" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mc-contacts-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/contacts/search": { - "post": { - "operationId": "POST_mc-contacts-search", - "summary": "Search Contacts", - "tags": ["Contacts"], - "description": "**Use this endpoint to locate contacts**.\n\nThe request body's `query` field accepts valid [SGQL](https://sendgrid.com/docs/for-developers/sending-email/segmentation-query-language/) for searching for a contact.\n\nBecause contact emails are stored in lower case, using SGQL to search by email address requires the provided email address to be in lower case. The SGQL `lower()` function can be used for this.\n\nOnly the first 50 contacts that meet the search criteria will be returned.\n\nIf the query takes longer than 20 seconds, a `408 Request Timeout` status will be returned.\n\nFormatting the `created_at` and `updated_at` values as Unix timestamps is deprecated. Instead they are returned as ISO format as string.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "query": { - "type": "string", - "description": "An SGQL search string or other pattern." - } - }, - "required": ["query"], - "example": { - "query": "email LIKE 'ENTER_COMPLETE_OR_PARTIAL_EMAIL_ADDRESS_HERE%' AND CONTAINS(list_ids, 'YOUR_LIST_IDs')" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/components/schemas/contact-details3" - } - }, - "_metadata": { - "$ref": "#/components/schemas/selfmetadata" - }, - "contact_count": { - "type": "number", - "description": "The total number of contacts matched." - } - }, - "required": ["contact_count"] - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "408": { - "description": "" - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_mc-contacts-search", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/contacts/imports": { - "put": { - "operationId": "PUT_mc-contacts-imports", - "summary": "Import Contacts", - "tags": ["Contacts"], - "description": "**This endpoint allows a CSV upload containing up to one million contacts or 5GB of data, whichever is smaller.**\n\nImports take place asynchronously: the endpoint returns a URL (`upload_uri`) and HTTP headers (`upload_headers`) which can subsequently be used to `PUT` a file of contacts to be imported into our system.\n\nUploaded CSV files may also be [gzip-compressed](https://en.wikipedia.org/wiki/Gzip).\n\nIn either case, you must include the field `file_type` with the value `csv` in your request body.\n\nThe `field_mappings` paramter is a respective list of field definition IDs to map the uploaded CSV columns to. It allows you to use CSVs where one or more columns are skipped (`null`) or remapped to the contact field. \n\nFor example, if `field_mappings` is set to `[null, \"w1\", \"_rf1\"]`, this means skip column 0, map column 1 to the custom field with the ID `w1`, and map column 2 to the reserved field with the ID `_rf1`. See the \"Get All Field Definitions\" endpoint to fetch your custom and reserved field IDs to use with `field_mappings`.\n\nOnce you recieve the response body you can then initiate a **second** API call where you use the supplied URL and HTTP header to upload your file. For example:\n\n`curl --upload-file \"file/path.csv\" \"URL_GIVEN\" -H 'HEADER_GIVEN'`\n\nIf you'd like to monitor the status of your import job, use the `job_id` and the \"Import Contacts Status\" endpoint.\n\nTwilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "list_ids": { - "type": "array", - "description": "All contacts will be added to each of the specified lists.", - "items": { - "type": "string" - } - }, - "file_type": { - "type": "string", - "enum": ["csv"], - "description": "Upload file type." - }, - "field_mappings": { - "type": "array", - "description": "Import file header to reserved/custom field mapping.", - "uniqueItems": false, - "minItems": 1, - "items": { - "anyOf": [ - { - "type": "string" - }, - { - "nullable": true - } - ] - } - } - }, - "required": ["file_type", "field_mappings"] - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "job_id": { - "type": "string", - "description": "The ID of the import job." - }, - "upload_uri": { - "type": "string", - "description": "The URI to PUT the upload file to." - }, - "upload_headers": { - "type": "array", - "description": "A list of headers that must be included in PUT request.", - "items": { - "type": "object", - "properties": { - "header": { - "type": "string" - }, - "value": { - "type": "string" - } - }, - "required": ["header", "value"] - } - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "uniqueItems": true, - "items": { - "$ref": "#/components/schemas/error" - } - } - }, - "required": ["errors"] - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "If any of the specified lists do not exist.", - "properties": { - "errors": { - "type": "array", - "uniqueItems": true, - "items": { - "$ref": "#/components/schemas/error" - } - } - }, - "required": ["errors"] - } - } - } - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PUT_mc-contacts-imports", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/contacts/imports/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_marketing-contacts-imports-id", - "summary": "Import Contacts Status", - "tags": ["Contacts"], - "description": "**This endpoint can be used to check the status of a contact import job**. \n\nUse the `job_id` from the \"Import Contacts,\" \"Add or Update a Contact,\" or \"Delete Contacts\" endpoints as the `id` in the path parameter.\n\nIf there is an error with your `PUT` request, download the `errors_url` file and open it to view more details.\n\nThe job `status` field indicates whether the job is `pending`, `completed`, `errored`, or `failed`. \n\nPending means not started. Completed means finished without any errors. Errored means finished with some errors. Failed means finshed with all errors, or the job was entirely unprocessable: for example, if you attempt to import file format we do not support.\n\nThe `results` object will have fields depending on the job type.\n\nTwilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contact-import" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "$ref": "#/components/schemas/error" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_marketing-contacts-imports-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/contacts/exports/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_mc-contacts-exports-id", - "summary": "Export Contacts Status", - "tags": ["Contacts"], - "description": "**This endpoint can be used to check the status of a contact export job**. \n\nTo use this call, you will need the `id` from the \"Export Contacts\" call.\n\nIf you would like to download a list, take the `id` that is returned from the \"Export Contacts\" endpoint and make an API request here to get the `urls`. Once you have the list of URLs, make a `GET` request on each URL to download your CSV file(s).\n\nTwilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contact-export" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/error" - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mc-contacts-exports-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/contacts/batch": { - "post": { - "operationId": "POST_marketing-contacts-batch", - "summary": "Get Batched Contacts by IDs", - "tags": ["Contacts"], - "description": "**This endpoint is used to retrieve a set of contacts identified by their IDs.**\n\nThis can be more efficient endpoint to get contacts than making a series of individual `GET` requests to the \"Get a Contact by ID\" endpoint.\n\nYou can supply up to 100 IDs. Pass them into the `ids` field in your request body as an array or one or more strings.\n\nTwilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "Array of IDs", - "properties": { - "ids": { - "maxItems": 100, - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": ["ids"], - "example": { - "ids": ["1234", "1235"] - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/components/schemas/contact-details3" - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "x-stoplight": { - "id": "POST_marketing-contacts-batch", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/contacts/search/emails": { - "post": { - "operationId": "POST_marketing-contacts-search-emails", - "summary": "Get Contacts by Emails", - "tags": ["Contacts"], - "description": "**This endpoint allows you to retrieve up to 100 contacts matching the searched `email` address(es), including any `alternate_emails`.** \n\nEmail addresses are unique to a contact, meaning this endpoint can treat an email address as a primary key to search by. The contact object associated with the address, whether it is their `email` or one of their `alternate_emails` will be returned if matched.\n\nEmail addresses in the search request do not need to match the case in which they're stored, but the email addresses in the result will be all lower case. Empty strings are excluded from the search and will not be returned.\n\nThis endpoint should be used in place of the \"Search Contacts\" endpoint when you can provide exact email addresses and do not need to include other [Segmentation Query Language (SGQL)](https://sendgrid.com/docs/for-developers/sending-email/segmentation-query-language/) filters when searching.\n\nIf you need to access a large percentage of your contacts, we recommend exporting your contacts with the \"Export Contacts\" endpoint and filtering the results client side.\n\nThis endpoint returns a `200` status code when any contacts match the address(es) you supplied. When searching multiple addresses in a single request, it is possible that some addresses will match a contact while others will not. When a partially successful search like this is made, the matching contacts are returned in an object and an error message is returned for the email address(es) that are not found. \n\nThis endpoint returns a `404` status code when no contacts are found for the provided email address(es).\n\nA `400` status code is returned if any searched addresses are invalid.\n\nTwilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "", - "properties": { - "emails": { - "type": "array", - "description": "One or more primary emails and/or alternate emails to search through your contacts for.", - "items": { - "type": "string", - "maxLength": 100 - } - } - }, - "required": ["emails"], - "example": { - "emails": [ - "jane_doe@example.com", - "john_doe@example.com", - "joann_doe@example.com" - ] - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "object", - "additionalProperties": false, - "patternProperties": { - "^[A-Za-z0-9\\._%\\+-]+@[A-Za-z0-9\\.-]+\\.[A-Za-z]{2,6}$": { - "type": "object", - "description": "This will be one of the specified email adresses.", - "properties": { - "contact": { - "$ref": "#/components/schemas/contact-details3" - }, - "error": { - "type": "string" - } - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "result": { - "jane_doe@example.com": { - "contact": { - "address_line_1": "", - "address_line_2": "", - "alternate_emails": ["janedoe@example1.com"], - "city": "", - "country": "", - "email": "jane_doe@example.com", - "first_name": "Jane", - "id": "asdf-Jkl-zxCvBNm", - "last_name": "Doe", - "list_ids": [], - "segment_ids": [], - "postal_code": "", - "state_province_region": "", - "phone_number": "", - "whatsapp": "", - "line": "", - "facebook": "", - "unique_name": "", - "custom_fields": {}, - "created_at": "2021-03-02T15:25:47Z", - "updated_at": "2021-03-30T15:26:16Z", - "_metadata": { - "self": "" - } - } - }, - "john_doe@example.com": { - "contact": { - "address_line_1": "", - "address_line_2": "", - "alternate_emails": [], - "city": "", - "country": "", - "email": "john_doe@example.com", - "first_name": "Jane", - "id": "asdf-Jkl-qWeRTy", - "last_name": "Doe", - "list_ids": [], - "segment_ids": [], - "postal_code": "", - "state_province_region": "", - "phone_number": "", - "whatsapp": "", - "line": "", - "facebook": "", - "unique_name": "", - "custom_fields": {}, - "created_at": "2020-01-02T15:25:47Z", - "updated_at": "2020-12-20T15:26:16Z", - "_metadata": { - "self": "" - } - } - }, - "joann_doe@example.com": { - "error": "contact not found" - } - } - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_marketing-contacts-search-emails", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/segments/2.0": { - "post": { - "operationId": "POST_segments", - "summary": "Create Segment", - "tags": ["Segmenting Contacts V2"], - "description": "Segment `name` has to be unique. A user can not create a new segment with an existing segment name.", - "requestBody": { - "$ref": "#/components/requestBodies/segment_write_v2" - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/segment_response" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/errors-seg-v2" - } - } - } - }, - "404": { - "description": "" - }, - "429": { - "description": "" - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/errors-seg-v2" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_segments", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_segments", - "summary": "Get List of Segments", - "tags": ["Segmenting Contacts V2"], - "description": "The query param `parent_list_ids` is treated as a filter. Any match will be returned. 0 matches will return a response code of 200 with an empty `results` array.\n\n`parent_list_ids` | `no_parent_list_id` | `result`\n-----------------:|:--------------------:|:-------------\nempty | false | all segments\nvalues | false | segments filtered by list_ids\nvalues | true | segments filtered by list_ids and segments with no parent list_ids\nempty | true | segments with no parent list_ids", - "parameters": [ - { - "name": "parent_list_ids", - "in": "query", - "description": "A comma separated list up to 50 in size, to filter segments on. Only segments that have any of these list ids as the parent list will be retrieved. This is different from the parameter of the same name used when creating a segment.", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "no_parent_list_id", - "in": "query", - "description": "If set to `true` segments with an empty value of `parent_list_id` will be returned in the filter. If the value is not present it defaults to 'false'.", - "required": false, - "schema": { - "type": "boolean", - "default": false - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/all_segments_response" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/errors-seg-v2" - } - } - } - }, - "404": { - "description": "" - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/errors-seg-v2" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_segments", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/segments/2.0/{segment_id}": { - "parameters": [ - { - "name": "segment_id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "patch": { - "operationId": "PATCH_segments-segment_id", - "summary": "Update Segment", - "tags": ["Segmenting Contacts V2"], - "description": "Segment `name` has to be unique. A user can not create a new segment with an existing segment name.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/segment_update" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/segment_response" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/errors-seg-v2" - } - } - } - }, - "429": { - "description": "" - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/errors-seg-v2" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_segments-segment_id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_segments-segment_id", - "summary": "Get Segment by ID", - "tags": ["Segmenting Contacts V2"], - "description": "", - "parameters": [ - { - "name": "contacts_sample", - "in": "query", - "description": "Defaults to `true`. Set to `false` to exclude the contacts_sample in the response.", - "schema": { - "type": "boolean" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/segment_response" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/errors-seg-v2" - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/errors-seg-v2" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_segments-segment_id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_segments-segment_id", - "summary": "Delete segment", - "tags": ["Segmenting Contacts V2 - Beta"], - "description": "**The Segmentation V2 API is currently in private beta. If you'd like to be added to the beta, please fill out this [form](https://docs.google.com/forms/d/e/1FAIpQLSd5zwC9dRk8lAp1oTWjdGc-aSY69flW_7wnutvKBhpUluSnfQ/viewform)**", - "responses": { - "202": { - "description": "" - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/errors-seg-v2" - } - } - } - }, - "404": { - "description": "" - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/errors-seg-v2" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_segments-segment_id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/senders": { - "post": { - "operationId": "POST_marketing-senders", - "summary": "Create a Sender Identity", - "tags": ["Senders"], - "description": "**This endpoint allows you to create a new sender identity.**\n\n*You may create up to 100 unique sender identities.*\n\nSender identities are required to be verified before use. If your domain has been authenticated, a new sender identity will auto verify on creation. Otherwise an email will be sent to the `from.email`.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "nickname": { - "type": "string", - "description": "A nickname for the sender identity. Not used for sending." - }, - "from": { - "type": "object", - "required": ["email", "name"], - "properties": { - "email": { - "type": "string", - "description": "This is where the email will appear to originate from for your recipient" - }, - "name": { - "type": "string", - "description": "This is the name appended to the from email field. IE - Your name or company name." - } - } - }, - "reply_to": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "This is the email that your recipient will reply to." - }, - "name": { - "type": "string", - "description": "This is the name appended to the reply to email field. IE - Your name or company name." - } - }, - "required": ["email"] - }, - "address": { - "type": "string", - "description": "The physical address of the sender identity." - }, - "address_2": { - "type": "string", - "description": "Additional sender identity address information." - }, - "city": { - "type": "string", - "description": "The city of the sender identity." - }, - "state": { - "type": "string", - "description": "The state of the sender identity." - }, - "zip": { - "type": "string", - "description": "The zipcode of the sender identity." - }, - "country": { - "type": "string", - "description": "The country of the sender identity." - } - }, - "required": ["nickname", "from", "address", "city", "country"], - "example": { - "nickname": "Example Orders", - "from": { - "email": "orders@example.com", - "name": "Example Orders" - }, - "reply_to": { - "email": "support@example.com", - "name": "Example Support" - }, - "address": "1234 Fake St.", - "address_2": "", - "city": "San Francisco", - "state": "CA", - "zip": "94105", - "country": "United States" - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/senderID" - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_marketing-senders", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/lists": { - "post": { - "operationId": "POST_mc-lists", - "summary": "Create List", - "tags": ["Lists"], - "description": "**This endpoint creates a new contacts list.**\n\nOnce you create a list, you can use the UI to [trigger an automation](https://sendgrid.com/docs/ui/sending-email/getting-started-with-automation/#create-an-automation) every time you add a new contact to the list.\n\nA link to the newly created object is in `_metadata`.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Your name for your list", - "minLength": 1, - "maxLength": 100 - } - }, - "required": ["name"], - "example": { - "name": "list-name" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/list" - }, - "examples": { - "response": { - "value": { - "id": "ca7a3796-e8a8-4029-9ccb-df8937940562", - "name": "list-name", - "contact_count": 0, - "_metadata": { - "self": "https://api.sendgrid.com/v3/marketing/lists/ca7a3796-e8a8-4029-9ccb-df8937940562" - } - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/error" - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_mc-lists", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_mc-lists", - "summary": "Get All Lists", - "tags": ["Lists"], - "description": "**This endpoint returns an array of all of your contact lists.**", - "parameters": [ - { - "name": "page_size", - "in": "query", - "description": "Maximum number of elements to return. Defaults to 100, returns 1000 max", - "required": false, - "schema": { - "type": "number", - "minimum": 1, - "maximum": 1000, - "default": 100 - } - }, - { - "name": "page_token", - "in": "query", - "required": false, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/components/schemas/list" - } - }, - "_metadata": { - "$ref": "#/components/schemas/metadata" - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "id": "abc12312-x3y4-1234-abcd-123qwe456rty", - "name": "list-name", - "contact_count": 0, - "_metadata": { - "self": "https://api.sendgrid.com/v3/marketing/lists/abc12312-x3y4-1234-abcd-123qwe456rty" - } - } - ], - "_metadata": { - "self": "https://api.sendgrid.com/v3/marketing/lists?page_size=100&page_token=" - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mc-lists", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/lists/{id}/contacts/count": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_mc-lists-id-contacts-count", - "summary": "Get List Contact Count", - "tags": ["Lists"], - "description": "**This endpoint returns the number of contacts on a specific list.**", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "contact_count": { - "type": "integer" - }, - "billable_count": { - "type": "integer" - } - } - }, - "examples": { - "response": { - "value": { - "contact_count": 0, - "billable_count:": 0 - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mc-lists-id-contacts-count", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/lists/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_mc-lists-id", - "summary": "Get a List by ID", - "tags": ["Lists"], - "description": "**This endpoint returns data about a specific list.**\n\nSetting the optional parameter `contact_sample=true` returns the `contact_sample` in the response body. Up to fifty of the most recent contacts uploaded or attached to a list will be returned, sorted alphabetically, by email address.\n\nThe full contact count is also returned.", - "parameters": [ - { - "name": "contact_sample", - "in": "query", - "description": "Setting this parameter to the true will cause the contact_sample to be returned", - "schema": { - "type": "boolean", - "default": false - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/list" - }, - { - "type": "object", - "properties": { - "contact_sample": { - "$ref": "#/components/schemas/contact-details2" - } - } - } - ] - }, - "examples": { - "response": { - "value": { - "contact_count": 2, - "contact_sample": { - "id": "c3445f88-5c69-4237-86e6-9ec9de958050", - "list_ids": ["199abb98-0af3-4a8d-b371-6811ff85d062"], - "created_at": "2620-06-16T17:03:54.867Z", - "updated_at": "4780-12-06T06:51:30.024Z" - }, - "_metadata": { - "self": "https://api.sendgrid.com/v3/marketing/lists/199abb98-0af3-4a8d-b371-6811ff85d062" - }, - "id": "199abb98-0af3-4a8d-b371-6811ff85d062", - "name": "list-name" - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/error" - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mc-lists-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_mc-lists-id", - "summary": "Update List", - "tags": ["Lists"], - "description": "**This endpoint updates the name of a list.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Your name for your list." - } - }, - "example": { - "name": "updated-list-name" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/list" - }, - "examples": { - "response": { - "value": { - "id": "abc12312-x3y4-1234-abcd-123qwe456rty", - "name": "updated-list-name", - "contact_count": 0, - "_metadata": { - "self": "https://api.sendgrid.com/v3/marketing/lists/abc12312-x3y4-1234-abcd-123qwe456rty" - } - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/error" - } - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_mc-lists-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_lists-id", - "summary": "Delete a list", - "tags": ["Lists"], - "description": "**This endpoint allows you to deletes a specific list.**\n\nOptionally, you can also delete contacts associated to the list. The query parameter, `delete_contacts=true`, will delete the list and start an asynchronous job to delete associated contacts.", - "parameters": [ - { - "name": "delete_contacts", - "in": "query", - "description": "Flag indicates that all contacts on the list are also to be deleted.", - "required": false, - "schema": { - "type": "boolean", - "default": false - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "The delete has been accepted and is processing.", - "properties": { - "job_id": { - "type": "string", - "description": "job_id of the async job" - } - } - }, - "examples": { - "response": { - "value": { - "job_id": "abc12312-x3y4-1234-abcd-123qwe456rty" - } - } - } - } - } - }, - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "string", - "description": "The delete has been processed. " - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object" - } - } - }, - "required": ["errors"] - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_lists-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/lists/{id}/contacts": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "delete": { - "operationId": "DELETE_mc-lists-id-contacts", - "summary": "Remove Contacts from a List", - "tags": ["Lists"], - "description": "**This endpoint allows you to remove contacts from a given list.**\n\nThe contacts will not be deleted. Only their list membership will be changed.", - "parameters": [ - { - "name": "contact_ids", - "in": "query", - "description": "comma separated list of contact ids", - "required": true, - "schema": { - "type": "string", - "minLength": 1 - } - } - ], - "responses": { - "202": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "The removal is accepted and processing.", - "properties": { - "job_id": { - "type": "string", - "description": "job_id of the async job" - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/error" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "description": "If the specified list id does not exist. If the specified contact does not exist." - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_mc-lists-id-contacts", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/field_definitions": { - "post": { - "operationId": "POST_mc-field_definitions", - "summary": "Create Custom Field Definition", - "tags": ["Custom Fields"], - "description": "**This endpoint creates a new custom field definition.**\n\nCustom field definitions are created with the given `name` and `field_type`. Although field names are stored in a case-sensitive manner, all field names must be case-insensitively unique. This means you may create a field named `CamelCase` or `camelcase`, but not both. Additionally, a Custom Field name cannot collide with any Reserved Field names. You should save the returned `id` value in order to update or delete the field at a later date. You can have up to 120 custom fields.\n\nThe custom field name should be created using only alphanumeric characters (A-Z and 0-9) and underscores (\\_). Custom fields can only begin with letters A-Z or underscores (_). The field type can be date, text, or number fields. The field type is important for creating segments from your contact database.\n\n**Note: Creating a custom field that begins with a number will cause issues with sending in Marketing Campaigns.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "field_type": { - "type": "string", - "enum": ["Text", "Number", "Date"] - } - }, - "required": ["name", "field_type"], - "example": { - "name": "custom_field_name", - "field_type": "Text" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/custom_field_definitions_response" - }, - { - "type": "object", - "properties": { - "_metadata": { - "$ref": "#/components/schemas/_metadata" - } - } - } - ] - }, - "examples": { - "response": { - "value": { - "id": "a1_T", - "name": "custom_field_name", - "field_type": "Text", - "_metadata": { - "self": "https://api.sendgrid.com/v3/marketing/field_definitions/a1_B" - } - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "uniqueItems": true, - "items": { - "$ref": "#/components/schemas/error" - } - } - }, - "required": ["errors"] - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_mc-field_definitions", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_mc-field_definitions", - "summary": "Get All Field Definitions", - "tags": ["Custom Fields"], - "description": "**This endpoint retrieves all defined Custom Fields and Reserved Fields.**", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "minProperties": 0, - "maxProperties": 120, - "properties": { - "custom_fields": { - "type": "array", - "items": { - "$ref": "#/components/schemas/custom_field_definitions_response" - } - }, - "reserved_fields": { - "$ref": "#/components/schemas/reserved_field_definitions_response" - }, - "_metadata": { - "$ref": "#/components/schemas/_metadata" - } - }, - "required": ["custom_fields", "reserved_fields"] - }, - "examples": { - "response": { - "value": { - "custom_fields": [ - { - "id": "w1", - "name": "num_orders", - "field_type": "Number" - }, - { - "id": "w2", - "name": "dob", - "field_type": "Date" - } - ], - "reserved_fields": [ - { - "id": "_rf0_T", - "name": "first_name", - "field_type": "Text" - }, - { - "id": "_rf1_T", - "name": "last_name", - "field_type": "Text" - }, - { - "id": "_rf2_T", - "name": "email", - "field_type": "Text" - }, - { - "id": "_rf3_T", - "name": "alternate_emails", - "field_type": "Text" - }, - { - "id": "_rf4_T", - "name": "address_line_1", - "field_type": "Text" - }, - { - "id": "_rf5_T", - "name": "address_line_2", - "field_type": "Text" - }, - { - "id": "_rf6_T", - "name": "city", - "field_type": "Text" - }, - { - "id": "_rf7_T", - "name": "state_province_region", - "field_type": "Text" - }, - { - "id": "_rf8_T", - "name": "postal_code", - "field_type": "Text" - }, - { - "id": "_rf9_T", - "name": "country", - "field_type": "Text" - }, - { - "id": "_rf10_T", - "name": "phone_number", - "field_type": "Text" - }, - { - "id": "_rf11_T", - "name": "whatsapp", - "field_type": "Text" - }, - { - "id": "_rf12_T", - "name": "line", - "field_type": "Text" - }, - { - "id": "_rf13_T", - "name": "facebook", - "field_type": "Text" - }, - { - "id": "_rf14_T", - "name": "unique_name", - "field_type": "Text" - }, - { - "id": "_rf15_T", - "name": "email_domains", - "field_type": "Text", - "read_only": true - }, - { - "id": "_rf16_D", - "name": "last_clicked", - "field_type": "Date", - "read_only": true - }, - { - "id": "_rf17_D", - "name": "last_opened", - "field_type": "Date", - "read_only": true - }, - { - "id": "_rf18_D", - "name": "last_emailed", - "field_type": "Date", - "read_only": true - }, - { - "id": "_rf19_T", - "name": "singlesend_id", - "field_type": "Text", - "read_only": true - }, - { - "id": "_rf20_T", - "name": "automation_id", - "field_type": "Text", - "read_only": true - }, - { - "id": "_rf21_D", - "name": "created_at", - "field_type": "Date", - "read_only": true - }, - { - "id": "_rf22_D", - "name": "updated_at", - "field_type": "Date", - "read_only": true - }, - { - "id": "_rf23_T", - "name": "contact_id", - "field_type": "Text", - "read_only": true - } - ], - "_metadata": { - "self": "https://example.com/marketing/field_definitions" - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mc-field_definitions", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/field_definitions/{custom_field_id}": { - "parameters": [ - { - "name": "custom_field_id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "patch": { - "operationId": "PATCH_mc-field_definitions-custom_field_id", - "summary": "Update Custom Field Definition", - "tags": ["Custom Fields"], - "description": "**This endopoint allows you to update a defined Custom Field.**\n\nOnly your Custom fields can be modified; Reserved Fields cannot be updated.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - } - }, - "required": ["name"], - "example": { - "name": "new_custom_field_name" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/custom_field_definitions_response" - }, - { - "type": "object", - "properties": { - "_metadata": { - "$ref": "#/components/schemas/_metadata" - } - } - } - ] - }, - "examples": { - "response": { - "value": { - "id": "a1_T", - "name": "custom_field_name", - "field_type": "Text", - "_metadata": { - "self": "https://api.sendgrid.com/v3/marketing/field_definitions/a1_B" - } - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "uniqueItems": true, - "items": { - "$ref": "#/components/schemas/error" - } - } - }, - "required": ["errors"] - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "uniqueItems": true, - "items": { - "$ref": "#/components/schemas/error" - } - } - }, - "required": ["errors"] - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_mc-field_definitions-custom_field_id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_mc-field_definitions-custom_field_id", - "summary": "Delete Custom Field Definition", - "tags": ["Custom Fields"], - "description": "**This endpoint deletes a defined Custom Field.**\n\nYou cand delete only Custom Fields; Reserved Fields cannot be deleted.", - "responses": { - "204": { - "description": "" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["errors"], - "properties": { - "errors": { - "type": "array", - "uniqueItems": true, - "items": { - "$ref": "#/components/schemas/error" - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_mc-field_definitions-custom_field_id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/segments": { - "post": { - "operationId": "POST_marketing-segments", - "summary": "Create Segment", - "tags": ["segmenting contacts", "Segmenting Contacts"], - "description": "**This endpoint allows you to create a segment.**", - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/segment_write_v2" - }, - { - "type": "object", - "properties": { - "parent_list_id": { - "type": "string", - "minLength": 36, - "maxLength": 36, - "format": "uuid", - "description": "The id of the list if this segment is a child of a list. This implies the query is rewritten as `(${query_dsl}) AND CONTAINS(list_ids, ${parent_list_id})`" - } - } - } - ] - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/full-segment" - }, - "examples": { - "response": { - "value": { - "id": "864feb2e-5e93-47bf-b63e-21746c988105", - "contacts_count": 0, - "created_at": "2921-01-27T19:33:36.479Z", - "sample_updated_at": "3407-09-25T04:25:02.140Z", - "updated_at": "4389-06-21T16:59:51.403Z", - "contact_summary": { - "contact_id": "1a541ca7-9fef-42c8-8947-f3f8a3b33ffe", - "primary_email": "D8OsYF5ok@YtX.kcg", - "first_name": "exercitation Duis nisi", - "last_name": "aut", - "address_line_1": "ut sunt Duis eu", - "address_line_2": "in culpa esse non", - "city": "ÔXƫɋƄř", - "state_province_region": "consequat culpa in", - "postal_code": -88086402, - "country": "eiusmod", - "custom_fields": { - "custom_field_name2": "dolore cillum", - "custom_field_name1": "est mollit officia adipisicing dolo" - }, - "list_ids": [ - "c856a255-12f1-4b55-8564-218fd7eb34a7", - "130c8813-0d6f-4b9e-b154-736bb9db2ff8", - "c245021d-4444-4086-a498-3ffee7fa8cdf" - ] - }, - "contacts_sample": [ - { - "id": "e70eac25-1431-4231-bccd-1cfab432301e", - "email": "KLTF@SurgGzlAxCPOqhOUHYNBLsfpfE.trh", - "alternate_emails": ["dTeJZgU5uN9UYSo@nfIB.ijxg"], - "first_name": "ullamco esse culpa do", - "last_name": "officia laboris veniam consequat", - "address_line_1": "in occaecat labore est tempor", - "address_line_2": "magna adipisicing", - "city": "ƞó", - "state_province_region": "culpa ut", - "postal_code": -75218567, - "country": "voluptate in in reprehenderit aliquip", - "custom_fields": { - "custom_field_name1": "amet deserunt mollit", - "custom_field_name2": "minim consequat id" - } - }, - { - "id": "db637d33-bce1-462c-ae9c-91ec4f761de6", - "email": "t7N5TjDmKhC0@gfdifW.ua", - "alternate_emails": [ - "gQol@Xcfilli.hc", - "n4K7OdaVQh@YfsnF.ie", - "TdnvS3nMStREn@miFjGzNDCPZWhiswJNxrFnOYdUAZEpesQ.yxpu", - "xRzGDTTzzbYK@eJ.wpgb", - "iI1rOpx2ct@aZhuYGZBxJLZ.phr" - ], - "first_name": "ea et eu", - "last_name": "velit Ut laborum ipsu", - "address_line_1": "labore", - "address_line_2": "non", - "city": "ĔȸąŸÂ¸ȠɏbɄ", - "state_province_region": "deserunt dolore", - "postal_code": -95171713, - "country": "do", - "list_ids": [ - "c712288b-2300-4069-bef4-2e05b5948ec3", - "9003ef29-5eb7-4951-898b-1b102e490d6e" - ], - "custom_fields": { - "custom_field_name1": "amet deserunt mollit", - "custom_field_name2": "minim consequat id" - } - } - ], - "name": "aute amet deserunt adipisicing", - "query_dsl": "email LIKE %twilio.com", - "next_sample_update": "culpa sit occaecat fugiat quis" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - }, - "required": ["message"] - } - } - }, - "required": ["errors"] - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_marketing-segments", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 201 - } - } - }, - "get": { - "operationId": "GET_marketing-segments", - "summary": "Get List of Segments", - "tags": ["segmenting contacts", "Segmenting Contacts"], - "description": "**This endpoint allows you to retrieve a list of segments.**\n\nThe query param `parent_list_ids` is treated as a filter. Any match will be returned. 0 matches will return a response code of 200 with an empty `results` array.\n\n`parent_list_ids` | `no_parent_list_id` | `result`\n-----------------:|:--------------------:|:-------------\nempty | false | all segments\nvalues | false | segments filtered by list_ids\nvalues | true | segments filtered by list_ids and segments with no parent list_ids\nempty | true | segments with no parent list_ids", - "parameters": [ - { - "name": "parent_list_ids", - "in": "query", - "description": "A comma separated list of list ids to be used when searching for segments with the specified parent_list_id, no more than 50 is allowed", - "schema": { - "type": "string" - } - }, - { - "name": "no_parent_list_id", - "in": "query", - "description": "If set to `true` segments with an empty value of `parent_list_id` will be returned in the filter. If the value is not present it defaults to 'false'.", - "schema": { - "type": "boolean", - "default": false - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "results": { - "type": "array", - "uniqueItems": true, - "minItems": 0, - "items": { - "$ref": "#/components/schemas/segment_summary" - } - } - }, - "required": ["results"] - }, - "examples": { - "response": { - "value": { - "results": [ - { - "id": "12099613-91e5-4d09-a900-df7626325288", - "contacts_count": 78434802, - "created_at": "2921-01-27T19:33:36.479Z", - "sample_updated_at": "4685-11-26T07:05:04.660Z", - "updated_at": "2883-07-10T13:13:37.697Z" - }, - { - "id": "60c37015-3734-4c8e-b293-68cfa2ae4fa5", - "contacts_count": 34177253, - "created_at": "2575-07-26T23:17:20.984Z", - "sample_updated_at": "3074-09-04T09:49:58.127Z", - "updated_at": "5116-10-15T07:37:40.838Z", - "parent_list_id": "fd38af3d-3f69-4947-8dca-5fa967e7be82", - "name": "amet" - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - }, - "required": ["message"] - } - } - }, - "required": ["errors"] - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_marketing-segments", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/segments/{segment_id}": { - "parameters": [ - { - "name": "segment_id", - "in": "path", - "required": true, - "schema": { - "type": "string", - "format": "uuid", - "minLength": 36, - "maxLength": 36 - } - } - ], - "get": { - "operationId": "GET_marketing-segments-segment_id", - "summary": "Get Segment by ID", - "tags": ["segmenting contacts", "Segmenting Contacts"], - "description": "**This endpoint allows you to retrieve a single segment by ID.**", - "parameters": [ - { - "name": "query_json", - "in": "query", - "description": "Defaults to `false`. Set to `true` to return the parsed SQL AST as a JSON object in the field `query_json`", - "schema": { - "type": "boolean" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/full-segment" - }, - "examples": { - "response": { - "value": { - "id": "3b049926-0a54-4a91-83f0-086ace63c530", - "contacts_count": -83213117, - "created_at": "2921-01-27T19:33:36.479Z", - "sample_updated_at": "3407-09-25T04:25:02.140Z", - "updated_at": "4389-06-21T16:59:51.403Z", - "contacts_sample": [ - { - "id": "e70eac25-1431-4231-bccd-1cfab432301e", - "email": "KLTF@SurgGzlAxCPOqhOUHYNBLsfpfE.trh", - "alternate_emails": ["dTeJZgU5uN9UYSo@nfIB.ijxg"], - "first_name": "ullamco esse culpa do", - "last_name": "officia laboris veniam consequat", - "address_line_1": "in occaecat labore est tempor", - "address_line_2": "magna adipisicing", - "city": "ƞó", - "state_province_region": "culpa ut", - "postal_code": -75218567, - "country": "voluptate in in reprehenderit aliquip", - "custom_fields": { - "custom_field_name1": "amet deserunt mollit", - "custom_field_name2": "minim consequat id" - } - }, - { - "id": "db637d33-bce1-462c-ae9c-91ec4f761de6", - "email": "t7N5TjDmKhC0@gfdifW.ua", - "alternate_emails": [ - "gQol@Xcfilli.hc", - "n4K7OdaVQh@YfsnF.ie", - "TdnvS3nMStREn@miFjGzNDCPZWhiswJNxrFnOYdUAZEpesQ.yxpu", - "xRzGDTTzzbYK@eJ.wpgb", - "iI1rOpx2ct@aZhuYGZBxJLZ.phr" - ], - "first_name": "ea et eu", - "last_name": "velit Ut laborum ipsu", - "address_line_1": "labore", - "address_line_2": "non", - "city": "ĔȸąŸÂ¸ȠɏbɄ", - "state_province_region": "deserunt dolore", - "postal_code": -95171713, - "country": "do", - "list_ids": [ - "c712288b-2300-4069-bef4-2e05b5948ec3", - "9003ef29-5eb7-4951-898b-1b102e490d6e" - ], - "custom_fields": { - "custom_field_name1": "amet deserunt mollit", - "custom_field_name2": "minim consequat id" - } - } - ], - "name": "enim et anim", - "query_dsl": "nostrud" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - }, - "required": ["message", "field"] - } - } - }, - "required": ["errors"] - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - }, - "required": ["message"] - } - } - }, - "required": ["errors"] - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_marketing-segments-segmentid", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_marketing-segments-segment_id", - "summary": "Update Segment", - "tags": ["segmenting contacts", "Segmenting Contacts"], - "description": "**This endpoint allows you to update a segment.**\n\nSegment `name` needs to be unique. A user can not update a segment name to an existing one.", - "requestBody": { - "$ref": "#/components/requestBodies/segment_write_v2" - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/full-segment" - }, - "examples": { - "response": { - "value": { - "id": "5fff6250-b766-4959-a183-2e1fa565c4ce", - "contacts_count": -35493018, - "created_at": "2014-12-23T17:18:52.907Z", - "sample_updated_at": "2146-04-13T16:46:32.328Z", - "updated_at": "4389-06-21T16:59:51.403Z", - "contacts_sample": [ - { - "id": "4cff9fdf-1bee-44f7-95dc-a101f9ed3cfe", - "email": "exmS@KIzibBSmaUUHQa.uvv", - "alternate_emails": [ - "qXP-RD97fLl@oEDaUynqnNRHJHdoJAWVGXwvI.qlv", - "W0ngFWmR@WcQuSbPFVPZvLrjCFadfimFi.eqf", - "mYBC0ea5UxFI@qwO.jh", - "Nhf1OmY@KCSjTQsXYpbKrBUsQFHrnLuY.oef" - ], - "first_name": "consequat nulla in", - "last_name": "irure nostrud elit eu", - "address_line_1": "deserunt cillum aliqua nostrud ullamco", - "address_line_2": "sint", - "city": "ŷ(ç", - "state_province_region": "minim", - "postal_code": 62721676, - "country": "consectetur quis voluptate", - "custom_fields": { - "custom_field_name1": "dolor aute irure Excepteur" - }, - "list_ids": [ - "f9d5987d-7a01-4a66-b77e-1f08a392304b", - "b4e3b028-01d4-428b-9ef5-24bcd90fa02c", - "fedab84f-9aa5-449d-99e2-7b1361f8ee61" - ] - }, - { - "id": "093a66b8-bca8-4d8a-b32a-091d939c1928", - "email": "atNeYGC4nbF42@VOCUWuGaYr.ystm", - "alternate_emails": [ - "Zs6vnQbMU@XTamDsXEGJWBMMEacOc.hitv", - "Epl@ySBrQCFJZnjggkAYLu.ppta" - ], - "first_name": "est", - "last_name": "in", - "address_line_1": "culpa eu eiusmod sint", - "address_line_2": "sed velit sint", - "city": "BĊJ", - "state_province_region": "Lorem Ut aliqua elit", - "postal_code": 33736880, - "country": "in laboris Excepteur consequat", - "custom_fields": { - "custom_field_name2": "culpa Excepteur", - "custom_field_name1": "esse magna Ut" - } - }, - { - "id": "08939f9c-2c87-4639-bd07-16d41f90a5eb", - "email": "Jx660QHClqRrC@SavQvcdRpJlLqepwoEUCm.ar", - "alternate_emails": [ - "S8u@ZVGjHsXdSWtlhhad.ximc", - "GA1MN72v3uA@MPDvMUmTYjwFCsEaGnFnvVzJVqUTl.ehws" - ], - "first_name": "sed eu veli", - "last_name": "aliqua sit culpa", - "address_line_1": "occaecat aute enim", - "address_line_2": "ipsum quis in", - "city": "ɌſĕĝȤ¶Ǖ", - "state_province_region": "ut nisi sed esse", - "postal_code": -66445052, - "custom_fields": { - "custom_field_name1": "dolor aute irure Excepteur" - }, - "country": "occaecat veniam" - }, - { - "id": "0667ed97-7b7b-44aa-a115-0301067660d7", - "email": "AnoFtJq@IolRDmfj.njt", - "alternate_emails": ["F5WhHCA3oL6Ix@wOKzwIsvHbFi.mrlc"], - "first_name": "do mollit velit", - "last_name": "voluptate dolor", - "address_line_1": "et incididunt", - "address_line_2": "veniam quis non exercitation Duis", - "city": "DzƐȹŲdž", - "state_province_region": "occaecat", - "postal_code": -19694583, - "country": "reprehenderit", - "custom_fields": { - "custom_field_name1": "dolor aute irure Excepteur" - }, - "list_ids": ["ffd225a8-2008-4457-87af-1cffff5b1ccb"] - }, - { - "id": "449767ca-d446-45f1-aa9b-432f441b5ca1", - "email": "kF4@gYYdAxzetJrWszLAHuBUTu.rzq", - "alternate_emails": [ - "ksqbx6BInlB@ouWBjjxwFBwVQjdnEKXy.xi", - "TAe7F2m8dFlF@SirYykzbe.aj", - "T9c2Y@HjVQY.zz", - "p7ShfET@vMMnTUqoqngPSEqbpyoeWN.jlqn", - "0VJSIhIUT2k@mJXVtdZVKKswW.xoca" - ], - "first_name": "irure laboris minim", - "last_name": "id nostrud aliqua sit", - "address_line_1": "dolor", - "address_line_2": "elit ex labore sunt aliquip", - "city": "ÝǘźƝǝƉ‘Ɲ", - "state_province_region": "nostrud Duis non nulla laborum", - "postal_code": 60466925, - "country": "id sunt nisi", - "custom_fields": { - "custom_field_name2": "enim quis", - "custom_field_name1": "amet" - }, - "list_ids": [ - "2870627c-b9ea-4dcf-bde0-36c3e0e3eca9", - "575d86aa-4dcc-4b7d-b7de-ded856913198", - "fb82a17f-5777-439d-9b8c-2c565c8ddf20" - ] - } - ], - "name": "List Name", - "query_dsl": "Email LIKE %twilio.com" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - }, - "required": ["message", "field"] - } - } - }, - "required": ["errors"] - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - }, - "required": ["message"] - } - } - }, - "required": ["errors"] - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_marketing-segments-segmentid", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_marketing-segments-segment_id", - "summary": "Delete Segment", - "tags": ["segmenting contacts", "Segmenting Contacts"], - "description": "**This endpoint allows you to delete a segment by `segment_id`.**\n\nNote that deleting a segment does not delete the contacts associated with the segment by default. Contacts associated with a deleted segment will remain in your list of all contacts and any other segments they belong to.", - "responses": { - "202": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - }, - "required": ["message", "field"] - } - } - }, - "required": ["errors"] - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - }, - "required": ["message"] - } - } - }, - "required": ["errors"] - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_marketing-segments-segmentid", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 202 - } - } - } - }, - "/marketing/segments/delete": { - "post": { - "operationId": "POST_marketing-segments-delete", - "summary": "Bulk Delete Segments", - "tags": ["Segmenting Contacts"], - "description": "This endpoint allows you to delete segments in bulk.\n\nIf the segments are used by automations or the segments do not exist in the database, the segment IDs that could not be deleted along with automation IDs that are associated to those segments will be returned.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ids": { - "type": "array", - "items": { - "type": "string", - "format": "uuid" - } - } - }, - "example": { - "ids": [ - "a14dcc63-d651-4c57-9826-4a3705f5c78d", - "f3de551e-dc5c-4d42-bd08-c7f87f87f0e8", - "1b8107b5-adf4-401c-8865-fa84ba178fb9", - "d7900715-c904-4728-acff-9ab79627579e", - "16641f5b-cfa3-41b9-9626-244488ee85b1" - ] - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Segment ID" - }, - "error": { - "type": "string", - "description": "error message that indicates why segment cannot be deleted (\"in-use\", \"segment not found\", \"invalid uuid\")" - }, - "resources": { - "type": "object", - "description": "resources in which segment is being used", - "properties": { - "type": { - "type": "string", - "description": "the type of resource in use (e.g., \"automation\")" - }, - "ids": { - "type": "array", - "description": "the resource ids", - "items": { - "type": "string" - } - } - } - } - } - } - } - } - } - } - } - }, - "202": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_marketing-segments-delete", - "public": false, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/singlesends": { - "post": { - "operationId": "POST_marketing-singlesends", - "summary": "Create Single Send", - "tags": ["Single Sends"], - "description": "**This endpoint allows you to create a new Single Send.**\n\nPlease note that if you are migrating from the previous version of Single Sends, you no longer need to pass a template ID with your request to this endpoint. Instead, you will pass all template data in the `email_config` object.", - "requestBody": { - "$ref": "#/components/requestBodies/singlesend_request" - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/singlesend_response" - }, - "examples": { - "response": { - "value": { - "name": "Example API Created Single Send", - "id": "27c21bbf-a12c-440b-b8bf-c526975328ca", - "status": "scheduled", - "created_at": "2020-05-18T17:28:27.272Z", - "send_at": "2020-06-16T00:19:55.106Z", - "categories": ["unique opens"], - "email_config": { - "subject": "", - "html_content": "", - "plain_content": "", - "generate_plain_content": true, - "editor": "code", - "suppression_group_id": null, - "custom_unsubscribe_url": null, - "sender_id": null, - "ip_pool": null - }, - "send_to": { - "list_ids": ["f2fe66a1-43f3-4e3a-87b1-c6a600d805f0"] - } - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_marketing-singlesends", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_marketing-singlesends", - "summary": "Get All Single Sends", - "tags": ["Single Sends"], - "description": "**This endpoint allows you to retrieve all your Single Sends.**\n\nReturns all of your Single Sends with condensed details about each, including the Single Sends' IDs. For more details about an individual Single Send, pass the Single Send's ID to the `/marketing/singlesends/{id}` endpoint.", - "parameters": [ - { - "name": "page_size", - "in": "query", - "schema": { - "type": "integer" - } - }, - { - "name": "page_token", - "in": "query", - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/components/schemas/singlesend_response_short" - } - }, - "_metadata": { - "$ref": "#/components/schemas/_metadata" - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_marketing-singlesends", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_marketing-singlesends", - "summary": "Bulk Delete Single Sends", - "tags": ["Single Sends"], - "description": "**This endpoint allows you to delete multiple Single Sends using an array of Single Sends IDs.**\n\nTo first retrieve all your Single Sends' IDs, you can make a GET request to the `/marketing/singlensends` endpoint.\n\nPlease note that a DELETE request is permanent, and your Single Sends will not be recoverable after deletion.", - "parameters": [ - { - "name": "ids", - "in": "query", - "description": "Single Send IDs to delete", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "maxItems": 50 - } - } - ], - "responses": { - "204": { - "description": "" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_marketing-singlesends", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/singlesends/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "post": { - "operationId": "POST_marketing-singlesends-id", - "summary": "Duplicate Single Send", - "tags": ["Single Sends"], - "description": "**This endpoint allows you to duplicate an existing Single Send using its Single Send ID.**\n\nDuplicating a Single Send is useful when you want to create a Single Send but don't want to start from scratch. Once duplicated, you can update or edit the Single Send by making a PATCH request to the `/marketing/singlesends/{id}` endpoint.\n \nIf you leave the `name` field blank, your duplicate will be assigned the name of the Single Send it was copied from with the text “Copy of ” prepended to it. The `name` field length is limited to 100 characters, so the end of the new Single Send name, including “Copy of ”, will be trimmed if the name exceeds this limit.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100, - "description": "The name of the duplicate Single Send. If you choose to leave the name field blank, your duplicate will be assigned the name of the Single Send it was copied from with the text 'Copy of ' prepended to it. The end of the new Single Send name, including 'Copy of ', will be trimmed if the name exceeds the character limit." - } - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/singlesend_response" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_marketing-singlesends-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_marketing-singlesends-id", - "summary": "Update Single Send", - "tags": ["Single Sends"], - "description": "**This endpoint allows you to update a Single Send using a Single Send ID.**\n\nYou only need to pass the fields you want to update. Any blank/missing fields will remain unaltered.", - "requestBody": { - "$ref": "#/components/requestBodies/singlesend_request" - }, - "responses": { - "202": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/singlesend_response" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_marketing-singlesends-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_marketing-singlesends-id", - "summary": "Get Single Send by ID", - "tags": ["Single Sends"], - "description": "**This endpoint allows you to retrieve details about one Single Send using a Single Send ID.**\n\nYou can retrieve all of your Single Sends by making a GET request to the `/marketing/singlesends` endpoint.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/singlesend_response" - }, - "examples": { - "response": { - "value": { - "name": "single-send-1", - "id": "2f6dec81-43b9-4c67-a890-3a38cb63b54a", - "status": "scheduled", - "created_at": "2020-12-13T16:24:42.013Z", - "send_to": { - "segment_ids": [ - "dad84de3-bec4-4e04-b132-2cbfd4bb3789", - "7dce758d-1155-4102-88d2-ca65565ac98b" - ], - "all": true - } - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_marketing-singlesends-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_marketing-singlesends-id", - "summary": "Delete Single Send by ID", - "tags": ["Single Sends"], - "description": "**This endpoint allows you to delete one Single Send using a Single Send ID.**\n\nTo first retrieve all your Single Sends' IDs, you can make a GET request to the `/marketing/singlensends` endpoint.\n\nPlease note that a `DELETE` request is permanent, and your Single Send will not be recoverable after deletion.", - "responses": { - "204": { - "description": "" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_marketing-singlesends-id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/singlesends/search": { - "post": { - "operationId": "POST_marketing-singlesends-search", - "summary": "Get Single Sends Search", - "tags": ["Single Sends"], - "description": "**This endpoint allows you to search for Single Sends based on specified criteria.**\n\nYou can search for Single Sends by passing a combination of values using the `name`, `status`, and `categories` request body fields.\n\nFor example, if you want to search for all Single Sends that are \"drafts\" or \"scheduled\" and also associated with the category \"shoes,\" your request body may look like the example below.\n\n```javascript\n{\n \"status\": [\n \"draft\",\n \"scheduled\"\n ],\n \"categories\": [\n \"shoes\"\n ],\n}\n```", - "parameters": [ - { - "name": "page_size", - "in": "query", - "schema": { - "type": "integer" - } - }, - { - "name": "page_token", - "in": "query", - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/singlesend_search" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/components/schemas/singlesend_response_short" - } - }, - "_metadata": { - "$ref": "#/components/schemas/_metadata" - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "id": "df25ffdf-6a96-458a-9419-6d87d3094c6b", - "name": "single-send-1", - "status": "triggered", - "categories": ["shoes"], - "is_abtest": true, - "abtest": null, - "updated_at": "3263-04-09T09:05:08.193Z", - "created_at": "4739-10-29T07:11:32.476Z", - "send_at": "2471-05-31T15:46:18.797Z" - } - ], - "_metadata": { - "self": "https://a/nwNSrPSWt7d", - "prev": "https://a/P0Enoayd", - "next": "https://a/DYEsTUDww9-", - "count": 1 - } - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_marketing-singlesends-search", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/singlesends/{id}/schedule": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "put": { - "operationId": "PUT_marketing-singlesends-id-schedule", - "summary": "Schedule Single Send", - "tags": ["Single Sends"], - "description": "**This endpoint allows you to schedule a Single Send for future delivery using a Single Send ID.**\n\nTo schedule a Single Send, you must pass a date string in ISO 8601 time format (yyyy-MM-ddTHH:mm:ssZ) using the required `send_at` field. For example, the ISO 8601 format for 9:00 AM UTC on May 6, 2020 would be `2020-05-06T09:00:00Z`. You may also pass the string `\"now\"` to send the Single Send immediately.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "send_at": { - "type": "string", - "description": "This is the ISO 8601 time at which to send the Single Send; must be in future, or the string \"now\"", - "format": "date-time" - } - }, - "required": ["send_at"], - "example": { - "send_at": "3752-01-28T23:21:52.575Z" - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "send_at": { - "type": "string", - "description": "", - "format": "date-time" - }, - "status": { - "type": "string", - "enum": ["scheduled"] - } - } - }, - "examples": { - "response": { - "value": { - "send_at": "3752-01-28T23:21:52.575Z", - "status": "scheduled" - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PUT_marketing-singlesends-id-schedule", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_marketing-singlesends-id-schedule", - "summary": "Delete Single Send Schedule", - "tags": ["Single Sends"], - "description": "**This endpoint allows you to cancel a scheduled Single Send using a Single Send ID.**\n\nMaking a DELETE request to this endpoint will cancel the scheduled sending of a Single Send. The request will not delete the Single Send itself. Deleting a Single Send can be done by passing a DELETE request to `/marketing/singlesends/{id}`.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/singlesend_schedule" - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_marketing-singlesends-id-schedule", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/singlesends/categories": { - "get": { - "operationId": "GET_marketing-singlesends-categories", - "summary": "Get All Categories", - "tags": ["Single Sends"], - "description": "**This endpoint allows you to retrieve all the categories associated with your Single Sends.**\n\nThis endpoint will return your latest 1,000 categories.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "categories": { - "type": "array", - "uniqueItems": true, - "maxItems": 1000, - "description": "list of latest one thousand unique categories associated with all Single Sends in ascending order", - "items": { - "type": "string" - } - } - } - }, - "examples": { - "response": { - "value": { - "categories": ["equipment", "shoes", "sports"] - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_marketing-singlesends-categories", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/test/send_email": { - "post": { - "operationId": "POST_marketing-test-send_email", - "summary": "Send a Test Marketing Email", - "tags": ["Send Test Email"], - "description": "**This endpoint allows you to send a test marketing email to a list of email addresses**.\n\nBefore sending a marketing message, you can test it using this endpoint. You may specify up to **10 contacts** in the `emails` request body field. You must also specify a `template_id` and include either a `from_address` or `sender_id`. You can manage your templates with the [Twilio SendGrid App](https://mc.sendgrid.com/dynamic-templates) or the [Transactional Templates API](https://sendgrid.api-docs.io/v3.0/transactional-templates).\n\n> Please note that this endpoint works with Dynamic Transactional Templates only. Legacy Transactional Templates will not be delivered.\n\nFor more information about managing Dynamic Transactional Templates, see [How to Send Email with Dynamic Transactional Templates](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/).\n\nYou can also test your Single Sends in the [Twilio SendGrid Marketing Campaigns UI](https://mc.sendgrid.com/single-sends).", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "template_id": { - "type": "string", - "format": "uuid", - "description": "The ID of the template that you would like to use. If you use a template that contains a subject and content (either text or HTML), then those values specified at the personalizations or message level will not be used." - }, - "version_id_override": { - "type": "string", - "format": "uuid", - "description": " You can override the active template with an alternative template version by passing the version ID in this field. If this field is blank, the active template version will be used." - }, - "sender_id": { - "type": "integer", - "description": "This ID must belong to a verified sender. Alternatively, you may supply a `from_address` email." - }, - "custom_unsubscribe_url": { - "type": "string", - "description": "A custom unsubscribe URL." - }, - "suppression_group_id": { - "type": "integer" - }, - "emails": { - "type": "array", - "uniqueItems": true, - "minItems": 1, - "maxItems": 10, - "items": { - "type": "string", - "format": "email" - }, - "description": "An array of email addresses you want to send the test message to." - }, - "from_address": { - "type": "string", - "description": "You can either specify this address or specify a verified sender ID.", - "format": "email" - } - }, - "required": ["template_id", "emails"], - "example": { - "template_id": "f8f77db8-b9fa-4b3c-9ee8-de3d582016b8", - "version_id_override": "7734f757-8eb8-4d22-b7f0-779a72f32986", - "sender_id": 6060664, - "custom_unsubscribe_url": "https://example.com/unsubscribe", - "suppression_group_id": 21865513, - "emails": ["janedoe@example.com", "tiramisu@example.com", "bundt@example.com"] - } - } - } - } - }, - "responses": { - "202": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_errorResponse_400" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_marketing-test-sendemail", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/stats/automations": { - "get": { - "operationId": "getall-automation-stats", - "summary": "Get All Automation Stats", - "tags": ["Marketing Campaigns Stats"], - "description": "**This endpoint allows you to retrieve stats for all your Automations.**\n\nBy default, all of your Automations will be returned, but you can specify a selection by passing in a comma-separated list of Automation IDs as the value of the query string parameter `automation_ids`.\n\nResponses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100.\n\nYou can retrieve a specific page of responses with the `page_token` query string parameter.", - "parameters": [ - { - "name": "automation_ids", - "in": "query", - "description": "This endpoint returns all automation IDs if no `automation_ids` are specified.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "maxItems": 25 - } - }, - { - "$ref": "#/components/parameters/trait_pagination_page_size" - }, - { - "$ref": "#/components/parameters/trait_pagination_page_token" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/automations-response" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "getall-automation-stats", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/stats/automations/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "get-automation-stat", - "summary": "Get Automation Stats by ID", - "tags": ["Marketing Campaigns Stats"], - "description": "**This endpoint allows you to retrieve stats for a single Automation using its ID.**\n\nMultiple Automation IDs can be retrieved using the \"Get All Automation Stats\" endpoint. Once you have an ID, this endpoint will return detailed stats for the single automation specified.\n\nYou may constrain the stats returned using the `start_date` and `end_date` query string parameters. You can also use the `group_by` and `aggregated_by` query string parameters to further refine the stats returned.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_automationQueryParams_group_by" - }, - { - "$ref": "#/components/parameters/trait_automationQueryParams_step_ids" - }, - { - "$ref": "#/components/parameters/trait_baseParams_aggregated_by" - }, - { - "$ref": "#/components/parameters/trait_baseParams_start_date" - }, - { - "$ref": "#/components/parameters/trait_baseParams_end_date" - }, - { - "$ref": "#/components/parameters/trait_baseParams_timezone" - }, - { - "$ref": "#/components/parameters/trait_pagination_page_size" - }, - { - "$ref": "#/components/parameters/trait_pagination_page_token" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/automations-response" - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_errorResponse_400" - }, - "404": { - "description": "" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "get-automation-stat", - "public": true, - "mock": { - "enabled": true, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/stats/singlesends": { - "get": { - "operationId": "getall-singlesend-stats", - "summary": "Get All Single Sends Stats", - "tags": ["Marketing Campaigns Stats"], - "description": "**This endpoint allows you to retrieve stats for all your Single Sends.**\n\nBy default, all of your Single Sends will be returned, but you can specify a selection by passing in a comma-separated list of Single Send IDs as the value of the query string parameter `singlesend_ids`.\n\nResponses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100.\n\nYou can retrieve a specific page of responses with the `page_token` query string parameter.", - "parameters": [ - { - "name": "singlesend_ids", - "in": "query", - "description": "This endpoint returns all Single Send IDs if no IDs are included in `singlesend_ids`.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "maxItems": 25 - } - }, - { - "$ref": "#/components/parameters/trait_pagination_page_size" - }, - { - "$ref": "#/components/parameters/trait_pagination_page_token" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/singlesends-response" - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_errorResponse_400" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "getall-singlesend-stats", - "public": true, - "mock": { - "enabled": true, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/stats/singlesends/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "get-singlesend-stat", - "summary": "Get Single Send Stats by ID", - "tags": ["Marketing Campaigns Stats"], - "description": "**This endpoint allows you to retrieve stats for an individual Single Send using a Single Send ID.**\n\nMultiple Single Send IDs can be retrieved using the \"Get All Single Sends Stats\" endpoint. Once you have an ID, this endpoint will return detailed stats for the Single Send specified.\n\nYou may constrain the stats returned using the `start_date` and `end_date` query string parameters. You can also use the `group_by` and `aggregated_by` query string parameters to further refine the stats returned.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_baseParams_aggregated_by" - }, - { - "$ref": "#/components/parameters/trait_baseParams_start_date" - }, - { - "$ref": "#/components/parameters/trait_baseParams_end_date" - }, - { - "$ref": "#/components/parameters/trait_baseParams_timezone" - }, - { - "$ref": "#/components/parameters/trait_pagination_page_size" - }, - { - "$ref": "#/components/parameters/trait_pagination_page_token" - }, - { - "$ref": "#/components/parameters/trait_singlesendQueryParams_group_by" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/singlesends-response" - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_errorResponse_400" - }, - "404": { - "description": "" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "get-singlesend-stat", - "public": true, - "mock": { - "enabled": true, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/stats/automations/{id}/links": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The ID of the Automation you want to get click tracking stats for. ", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "get": { - "operationId": "get-automation-link-stat", - "summary": "Get Automation Click Tracking Stats by ID", - "tags": ["Marketing Campaigns Stats"], - "description": "**This endpoint lets you retrieve click-tracking stats for a single Automation**.\n\nThe stats returned list the URLs embedded in your Automation and the number of clicks each one received.\n\nResponses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100.\n\nYou can retrieve a specific page of responses with the `page_token` query string parameter.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_automationQueryParams_group_by" - }, - { - "$ref": "#/components/parameters/trait_automationQueryParams_step_ids" - }, - { - "$ref": "#/components/parameters/trait_pagination_page_size" - }, - { - "$ref": "#/components/parameters/trait_pagination_page_token" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/automations-link-stats-response" - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_errorResponse_400" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "get-automation-link-stat", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/stats/singlesends/{id}/links": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "get-singlesend-link-stat", - "summary": "Get Single Send Click Tracking Stats by ID", - "tags": ["Marketing Campaigns Stats"], - "description": "**This endpoint lets you retrieve click-tracking stats for one Single Send**.\n\nThe stats returned list the URLs embedded in the specified Single Send and the number of clicks each one received.\n\nResponses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100.\n\nYou can retrieve a specific page of responses with the `page_token` query string parameter.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_pagination_page_size" - }, - { - "$ref": "#/components/parameters/trait_pagination_page_token" - }, - { - "$ref": "#/components/parameters/trait_singlesendQueryParams2_group_by" - }, - { - "$ref": "#/components/parameters/trait_singlesendQueryParams2_ab_variation_id" - }, - { - "$ref": "#/components/parameters/trait_singlesendQueryParams2_ab_phase_id" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/singlesends-link-stats-response" - } - } - } - }, - "400": { - "$ref": "#/components/responses/trait_errorResponse_400" - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "get-singlesend-link-stat", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/stats/singlesends/export": { - "get": { - "operationId": "get-singlesend-stats-export", - "summary": "Export Single Send Stats", - "tags": ["Marketing Campaigns Stats"], - "description": "**This endpoint allows you to export Single Send stats as .CSV data**.\n\nYou can specify one Single Send or many: include as many Single Send IDs as you need, separating them with commas, as the value of the `ids` query string paramter.\n\nThe data is returned as plain text response but in .CSV format, so your application making the call can present the information in whatever way is most appropriate, or just save the data as a .csv file.", - "parameters": [ - { - "name": "ids", - "in": "query", - "description": "The IDs of Single Sends for which to export stats.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "maxItems": 50 - } - }, - { - "name": "timezone", - "in": "query", - "description": "The [IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones) string representing the timezone in which the stats are to be presented; i.e. `\"America/Chicago\"`. This parameter changes the timezone format only; it does not alter which stats are returned.", - "schema": { - "type": "string", - "default": "UTC" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "string", - "description": "CSV data" - } - } - } - }, - "400": { - "description": "" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "get-singlesend-stats-export", - "public": true, - "mock": { - "enabled": true, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/marketing/stats/automations/export": { - "get": { - "operationId": "get-automations-stats-export", - "summary": "Export Automation Stats", - "tags": ["Marketing Campaigns Stats"], - "description": "**This endpoint allows you to export Automation stats as CSV data**.\n\nYou can specify one Automation or many: include as many Automation IDs as you need, separating them with commas, as the value of the `ids` query string paramter.\n\nThe data is returned as plain text response but in CSV format, so your application making the call can present the information in whatever way is most appropriate, or just save the data as a `.csv` file.", - "parameters": [ - { - "name": "ids", - "in": "query", - "description": "The IDs of Automations for which to export stats.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "maxItems": 50 - } - }, - { - "name": "timezone", - "in": "query", - "description": "The [IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones) string representing the timezone in which the stats are to be presented; i.e. `\"America/Chicago\"`. This parameter changes the timezone format only; it does not alter which stats are returned.", - "schema": { - "type": "string", - "default": "UTC" - } - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "string", - "description": "CSV data" - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "get-automations-stats-export", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/senders": { - "post": { - "operationId": "POST_senders", - "summary": "Create a Sender Identity", - "tags": ["Sender Identities API"], - "description": "**This endpoint allows you to create a new sender identity.**\n\nYou may create up to 100 unique sender identities.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/sender-id-request" - }, - { - "type": "object", - "properties": { - "from": { - "type": "object", - "required": ["email"] - }, - "reply_to": { - "type": "object", - "required": ["email"] - } - }, - "required": ["nickname", "address", "city", "country"] - } - ], - "example": { - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States" - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/senderID" - }, - "examples": { - "response": { - "value": { - "id": 1, - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States", - "verified": true, - "updated_at": 1449872165, - "created_at": 1449872165, - "locked": false - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "The JSON you have submitted cannot be parsed.", - "field": "" - }, - { - "message": "You've reached your limit of 100 sender identities. Please delete one or more and try again.", - "field": "" - }, - { - "message": "nickname is required.", - "field": "nickname" - }, - { - "message": "You already have a sender identity with the same nickname.", - "field": "nickname" - }, - { - "message": "from_name is required.", - "field": "from_name" - }, - { - "message": "from_email is required.", - "field": "from_email" - }, - { - "message": "From email is not a valid email address.", - "field": "from_email" - }, - { - "message": "reply_to is required.", - "field": "reply_to" - }, - { - "message": "Reply to email is not a valid email address.", - "field": "reply_to" - }, - { - "message": "address is required.", - "field": "address" - }, - { - "message": "city is required.", - "field": "city" - }, - { - "message": "country is required.", - "field": "country" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_senders", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_v3-senders", - "summary": "Get all Sender Identities", - "tags": ["Sender Identities API"], - "description": "**This endpoint allows you to retrieve a list of all sender identities that have been created for your account.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/components/schemas/senderID" - } - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "id": 1, - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States", - "verified": true, - "updated_at": 1449872165, - "created_at": 1449872165, - "locked": false - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_v3-senders", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/senders/{sender_id}": { - "parameters": [ - { - "name": "sender_id", - "in": "path", - "description": "The ID of the sender identity that you want to retrieve.", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "get": { - "operationId": "GET_v3-senders-sender_id", - "summary": "View a Sender Identity", - "tags": ["Sender Identities API"], - "description": "**This endpoint allows you to retrieve a specific sender identity.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/senderID" - }, - "examples": { - "response": { - "value": { - "id": 1, - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States", - "verified": true, - "updated_at": 1449872165, - "created_at": 1449872165, - "locked": false - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "resource not found", - "field": "id" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_v3-senders-sender_id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_v3-senders-sender_id", - "summary": "Update a Sender Identity", - "tags": ["Sender Identities API"], - "description": "**This endpoint allows you to update a sender identity.**\n\nUpdates to `from.email` require re-verification.\n\nPartial updates are allowed, but fields that are marked as \"required\" in the POST (create) endpoint must not be nil if that field is included in the PATCH request.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sender-id-request" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/senderID" - }, - "examples": { - "response": { - "value": { - "id": 1, - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States", - "verified": true, - "updated_at": 1449872165, - "created_at": 1449872165, - "locked": false - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "The JSON you have submitted cannot be parsed.", - "field": "" - }, - { - "message": "nickname is required.", - "field": "nickname" - }, - { - "message": "You already have a sender identity with the same nickname.", - "field": "nickname" - }, - { - "message": "from_name is required.", - "field": "from_name" - }, - { - "message": "from_email is required.", - "field": "from_email" - }, - { - "message": "From email is not a valid email address.", - "field": "from_email" - }, - { - "message": "reply_to is required.", - "field": "reply_to" - }, - { - "message": "Reply to email is not a valid email address.", - "field": "reply_to" - }, - { - "message": "address is required.", - "field": "address" - }, - { - "message": "city is required.", - "field": "city" - }, - { - "message": "country is required.", - "field": "country" - } - ] - } - } - } - } - } - }, - "403": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "You may only update a sender identity when it is unlocked.", - "field": "locked" - } - ] - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "resource not found", - "field": "id" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_v3-senders-sender_id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_v3-senders-sender_id", - "summary": "Delete a Sender Identity", - "tags": ["Sender Identities API"], - "description": "**This endoint allows you to delete one of your sender identities.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - }, - "403": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "You may only delete a sender identity when it is unlocked.", - "field": "locked" - } - ] - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "resource not found", - "field": "id" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_v3-senders-sender_id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/senders/{sender_id}/resend_verification": { - "parameters": [ - { - "name": "sender_id", - "in": "path", - "description": "The ID of the sender identity for which you would like to resend a verification email.", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "post": { - "operationId": "POST_v3-senders-sender_id-resend_verification", - "summary": "Resend Sender Identity Verification", - "tags": ["Sender Identities API"], - "description": "**This enpdoint allows you to resend a sender identity verification email.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "The Sender Identity is already verified. No email sent.", - "field": "" - } - ] - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "resource not found", - "field": "id" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_v3-senders-sender_id-resend_verification", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/contactdb/lists": { - "post": { - "operationId": "POST_contactdb-lists", - "summary": "Create a List", - "tags": ["Contacts API - Lists"], - "description": "**This endpoint allows you to create a list for your recipients.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "title": "Create a List request", - "type": "object", - "properties": { - "name": { - "type": "string" - } - }, - "required": ["name"], - "example": { - "name": "your list name" - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_list" - }, - "examples": { - "response": { - "value": { - "id": 1, - "name": "your list name", - "recipient_count": 0 - } - } - } - } - } - }, - "400": { - "description": "\"name\" : \"Returned if list name is a duplicate of an existing list or segment\"\n\"name\" : \"Returned if list name is not a string\"\n\"\" : \"Returned if request body is invalid JSON\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "Returned if request body is invalid JSON" - }, - { - "field": "name", - "message": "Returned if list name is not a string" - }, - { - "field": "name", - "message": "Returned if list name is a duplicate of an existing list or segment" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_contactdb-lists", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_contactdb-lists", - "summary": "Retrieve all lists", - "tags": ["Contacts API - Lists"], - "description": "**This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "List All Lists response", - "type": "object", - "properties": { - "lists": { - "type": "array", - "items": { - "$ref": "#/components/schemas/contactdb_list" - } - } - }, - "required": ["lists"] - }, - "examples": { - "response": { - "value": { - "lists": [ - { - "id": 1, - "name": "the jones", - "recipient_count": 1 - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-lists", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_contactdb-lists", - "summary": "Delete Multiple lists", - "tags": ["Contacts API - Lists"], - "description": "**This endpoint allows you to delete multiple recipient lists.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [1, 2, 3, 4] - } - } - } - }, - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "nullable": true - } - } - } - }, - "400": { - "description": "\"id\" : \"Returned if all list ids are not valid\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "list id was invalid" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_contactdb-lists", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/contactdb/lists/{list_id}": { - "parameters": [ - { - "name": "list_id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_contactdb-lists-list_id", - "summary": "Retrieve a single list", - "tags": ["Contacts API - Lists"], - "description": "**This endpoint allows you to retrieve a single recipient list.**", - "parameters": [ - { - "name": "list_id", - "in": "query", - "description": "The ID of the list to retrieve.", - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_list" - }, - "examples": { - "response": { - "value": { - "id": 1, - "name": "listname", - "recipient_count": 0 - } - } - } - } - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not valid\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "invalid id" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "List ID does not exist" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-lists-listid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_contactdb-lists-list_id", - "summary": "Update a List", - "tags": ["Contacts API - Lists"], - "description": "**This endpoint allows you to update the name of one of your recipient lists.**", - "parameters": [ - { - "name": "list_id", - "in": "query", - "description": "The ID of the list you are updating.", - "required": true, - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "title": "Update a List request", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The new name for your list. " - } - }, - "required": ["name"], - "example": { - "name": "newlistname" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the list" - }, - "name": { - "type": "string", - "description": "The new name for the list" - }, - "recipient_count": { - "type": "integer", - "description": "The number of recipients on the list" - } - } - }, - "examples": { - "response": { - "value": { - "id": 1234, - "name": "2016 iPhone Users", - "recipient_count": 0 - } - } - } - } - } - }, - "400": { - "description": "\"name\" : \"Returned if list name is a duplicate of existing list or segment\"\n\"name\" : \"Returned if list name is invalid or not provided\"\n\"list_id\" : \"Returned if list_id is not valid\"\n\"\" : \"Returned if request body is invalid JSON\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "invalid id" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "List ID does not exist" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_contactdb-lists-listid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_contactdb-lists-list_id", - "summary": "Delete a List", - "tags": ["Contacts API - Lists"], - "description": "**This endpoint allows you to delete a specific recipient list with the given ID.**", - "parameters": [ - { - "name": "delete_contacts", - "in": "query", - "description": "Adds the ability to delete all contacts on the list in addition to deleting the list.", - "schema": { - "type": "boolean", - "enum": [true, false] - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/DELETE_contactdb-lists-list_idBody" - }, - "responses": { - "202": { - "description": "", - "content": { - "application/json": { - "schema": { - "nullable": true - } - } - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not valid\"\n\"delete_contacts\" : \"Returned if delete_contacts is not valid\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "delete_contacts", - "message": "delete_contacts not a bool" - }, - { - "field": "list_id", - "message": "Returned if list_id is not valid" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "List not found: 5" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_contactdb-lists-listid", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/contactdb/lists/{list_id}/recipients": { - "parameters": [ - { - "name": "list_id", - "in": "path", - "description": "The id of the list of recipients you want to retrieve.", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "get": { - "operationId": "GET_contactdb-lists-list_id-recipients", - "summary": "Retrieve all recipients on a List", - "tags": ["Contacts API - Lists"], - "description": "**This endpoint allows you to retrieve all recipients on the list with the given ID.**", - "parameters": [ - { - "name": "page", - "in": "query", - "description": "Page index of first recipient to return (must be a positive integer)", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "name": "page_size", - "in": "query", - "description": "Number of recipients to return at a time (must be a positive integer between 1 and 1000)", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "name": "list_id", - "in": "query", - "description": "The ID of the list whose recipients you are requesting.", - "required": true, - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "$ref": "#/components/schemas/contactdb_recipient" - } - } - } - }, - "examples": { - "response": { - "value": { - "recipients": [ - { - "created_at": 1433348344, - "custom_fields": [ - { - "id": 6234, - "name": "age", - "type": "number", - "value": null - }, - { - "id": 6233, - "name": "country", - "type": "text", - "value": null - }, - { - "id": 6235, - "name": "fname", - "type": "text", - "value": "Example" - }, - { - "id": 6239, - "name": "lname", - "type": "text", - "value": "User" - }, - { - "id": 6240, - "name": "lname", - "type": "text", - "value": null - } - ], - "email": "example@example.com", - "first_name": "Example", - "id": "ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv==", - "last_clicked": 1438616117, - "last_emailed": 1438613272, - "last_name": "User", - "last_opened": 1438616109, - "updated_at": 1438616119 - } - ] - } - } - } - } - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not a valid integer\"\n\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"\n\"page_size\" : \"Returned if page_size is less than 1 or greater than 1000\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is not a valid integer" - }, - { - "field": "page", - "message": "Returned if page is not a valid integer" - }, - { - "field": "page", - "message": "Returned if page is less than 1" - }, - { - "field": "page_size", - "message": "Returned if page_size is not a valid integer" - }, - { - "field": "page_size", - "message": "Returned if page_size is less than 1 or greater than 1000" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", - "content": { - "application/json": { - "schema": { - "type": "object" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-lists-listid-recipients", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "post": { - "operationId": "POST_contactdb-lists-list_id-recipients", - "summary": "Add Multiple Recipients to a List", - "tags": ["Contacts API - Lists"], - "description": "**This endpoint allows you to add multiple recipients to a list.**\n\nAdds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "integer" - }, - "example": [1, 2] - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "nullable": true - } - } - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not a valid integer\"\n\"\" : \"Returned if no valid recipient ids were passed\"\n\"\" : \"Returned if no recipients were added\"\n\"\" : \"Returned if request body is invalid JSON\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "list_id", - "message": "list_id is invalid" - }, - { - "field": "recipient_id", - "message": "no valid recipients were provided" - }, - { - "field": null, - "message": "no recipients were added" - }, - { - "field": null, - "message": "request body is invalid JSON" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"list_id\": \"Returned if list_id does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "list_id", - "message": "list_id does not exist" - }, - { - "field": "recipient_id", - "message": "recipient_id does not exist" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_contactdb-lists-listid-recipients", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/contactdb/lists/{list_id}/recipients/{recipient_id}": { - "parameters": [ - { - "name": "list_id", - "in": "path", - "description": "The ID of the list that you want to add the recipient to.", - "required": true, - "schema": { - "type": "integer" - } - }, - { - "name": "recipient_id", - "in": "path", - "description": "The ID of the recipient you are adding to the list.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "post": { - "operationId": "POST_contactdb-lists-list_id-recipients-recipient_id", - "summary": "Add a Single Recipient to a List", - "tags": ["Contacts API - Lists"], - "description": "**This endpoint allows you to add a single recipient to a list.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "nullable": true - } - } - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is invalid\"\n\"recipient_id\" : \"Returned if recipient_id is invalid\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - }, - { - "field": "recipient_id", - "message": "Returned if recipient_id is invalid" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"\n\"recipient_id\" : \"Returned if recipient_id does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id does not exist" - }, - { - "field": "recipient_id", - "message": "Returned if recipient_id does not exist" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_contactdb-lists-listid-recipients-recipientid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_contactdb-lists-list_id-recipients-recipient_id", - "summary": "Delete a Single Recipient from a Single List", - "tags": ["Contacts API - Lists"], - "description": "**This endpoint allows you to delete a single recipient from a list.**", - "parameters": [ - { - "name": "list_id", - "in": "query", - "description": "The ID of the list you are taking this recipient away from.", - "required": true, - "schema": { - "type": "integer" - } - }, - { - "name": "recipient_id", - "in": "query", - "description": "The ID of the recipient to take off the list.", - "required": true, - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/DELETE_contactdb-lists-list_idBody" - }, - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "nullable": true - } - } - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not valid\"\n\"recipient_id\" : \"Returned if recipient_id is not valid\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - }, - { - "field": "recipient_id", - "message": "no valid recipients were provided" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"\n\"recipient_id\" : \"Returned if recipient_id does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id does not exist" - }, - { - "field": "recipient_id", - "message": "Returned if recipient_id does not exist" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_contactdb-lists-listid-recipients-recipientid", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/contactdb/recipients": { - "post": { - "operationId": "POST_contactdb-recipients", - "summary": "Add recipients", - "tags": ["Contacts API - Recipients"], - "description": "**This endpoint allows you to add a Marketing Campaigns recipient.**\n\nYou can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides.\n\nThe rate limit is three requests every 2 seconds. You can upload 1000 contacts per request. So the maximum upload rate is 1500 recipients per second.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address of the recipient.", - "format": "email" - }, - "first_name": { - "type": "string", - "description": "The first name of the recipient." - }, - "last_name": { - "type": "string", - "description": "The last name of the recipient." - }, - "age": { - "type": "integer" - } - }, - "required": ["email"] - }, - "example": [ - { - "email": "example@example.com", - "first_name": "", - "last_name": "User", - "age": 25 - }, - { - "email": "example2@example.com", - "first_name": "Example", - "last_name": "User", - "age": 25 - } - ] - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_recipient_response" - }, - "examples": { - "response": { - "value": { - "error_count": 1, - "error_indices": [2], - "new_count": 2, - "persisted_recipients": ["YUBh", "bWlsbGVyQG1pbGxlci50ZXN0"], - "updated_count": 0, - "errors": [ - { - "message": "Invalid email.", - "error_indices": [2] - } - ] - } - } - } - } - } - }, - "400": { - "description": "\"\" : \"Returned if request body is not valid json\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "Request body is not valid json" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_contactdb-recipients", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_contactdb-recipients", - "summary": "Update Recipient", - "tags": ["Contacts API - Recipients"], - "description": "**This endpoint allows you to update one or more recipients.**\n\nThe body of an API call to this endpoint must include an array of one or more recipient objects.\n\nIt is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "email": { - "type": "string", - "format": "email" - }, - "last_name": { - "type": "string", - "description": "The last name of the recipient. This is one of the default custom fields." - }, - "first_name": { - "type": "string", - "description": "The first name of the recipient. This is one of the default custom fields." - } - }, - "required": ["email"] - }, - "example": [ - { - "email": "jones@example.com", - "last_name": "Jones", - "first_name": "Guy" - } - ] - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_recipient_response" - } - } - } - }, - "400": { - "description": "\"\" : \"Returned if request body is not valid json\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "Request body is not valid json" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_contactdb-recipients", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_contactdb-recipients", - "summary": "Delete Recipients", - "tags": ["Contacts API - Recipients"], - "description": "**This endpoint allows you to deletes one or more recipients.**\n\nThe body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "example": ["recipient_id1", "recipient_id2"] - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "400": { - "description": "\"\" : \"Returned if no recipients are deleted\"\n\"\" : \"Returned if all of the provided recipient ids are invalid\"\n\"\" : \"Returned if request body is not valid json\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "No recipient ids provided" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_contactdb-recipients", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_contactdb-recipients", - "summary": "Retrieve recipients", - "tags": ["Contacts API - Recipients"], - "description": "**This endpoint allows you to retrieve all of your Marketing Campaigns recipients.**\n\nBatch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of\nthe list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.", - "parameters": [ - { - "name": "page", - "in": "query", - "description": "Page index of first recipients to return (must be a positive integer)", - "schema": { - "type": "integer" - } - }, - { - "name": "page_size", - "in": "query", - "description": "Number of recipients to return at a time (must be a positive integer between 1 and 1000)", - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "List Recipients response", - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "type": "object" - } - } - }, - "required": ["recipients"] - } - } - } - }, - "400": { - "description": "\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"\n\"page_size\" : \"Returned if page_size is less than 1 or greater than 1000\"", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-recipients", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/contactdb/status": { - "get": { - "operationId": "GET_contactdb-status", - "summary": "Get Recipient Upload Status", - "tags": ["Contacts API - Recipients"], - "description": "**This endpoint allows you to check the upload status of a Marketing Campaigns recipient.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "status": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "default": "", - "description": "Valid values are \"worker_delay\" and \"worker_delay_seconds\" (the second value appears only if \"worker_delay\" has a value of \"delayed\")." - }, - "value": { - "type": "string", - "default": "", - "description": "Valid values for the ID \"worker_delay\" are \"OK\" or \"Delayed\". Valid values for the ID \"worker_delay_seconds\" is the time of delay to upload." - }, - "": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "status": [ - { - "id": "worker_delay", - "value": "delayed" - }, - { - "id": "worker_delay_seconds", - "value": "75.0" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-status", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/contactdb/recipients/{recipient_id}": { - "parameters": [ - { - "name": "recipient_id", - "in": "path", - "description": "The ID of the recipient that you want to retrieve.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_contactdb-recipients-recipient_id", - "summary": "Retrieve a single recipient", - "tags": ["Contacts API - Recipients"], - "description": "**This endpoint allows you to retrieve a single recipient by ID from your contact database.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_recipient" - } - } - } - }, - "400": { - "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"recipient_id\" : \"Returned if record for recipient id does not exist\"", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-recipients-recipientid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_contactdb-recipients-recipient_id", - "summary": "Delete a Recipient", - "tags": ["Contacts API - Recipients"], - "description": "**This endpoint allows you to delete a single recipient with the given ID from your contact database.**\n\n> Use this to permanently delete your recipients from all of your contact lists and all segments if required by applicable law.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "400": { - "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "recipient not found" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"recipient_id\" : \"Returned if record for recipient id does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "recipient_id is not valid" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_contactdb-recipients-recipientid", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/contactdb/recipients/{recipient_id}/lists": { - "parameters": [ - { - "name": "recipient_id", - "in": "path", - "description": "The ID of the recipient for whom you are retrieving lists.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_contactdb-recipients-recipient_id-lists", - "summary": "Retrieve the lists that a recipient is on", - "tags": ["Contacts API - Recipients"], - "description": "**This endpoint allows you to retrieve the lists that a given recipient belongs to.**\n\nEach recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "lists": { - "type": "array", - "items": { - "$ref": "#/components/schemas/contactdb_list" - } - } - } - }, - "examples": { - "response": { - "value": { - "lists": [ - { - "id": 1234, - "name": "Example list", - "recipient_count": 42 - } - ] - } - } - } - } - } - }, - "400": { - "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "recipient ID is invalid" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"recipient_id\" : \"Returned if record for the recipient id does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "recipient id not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-recipients-recipientid-lists", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/contactdb/recipients/billable_count": { - "get": { - "operationId": "GET_contactdb-recipients-billable_count", - "summary": "Retrieve the count of billable recipients", - "tags": ["Contacts API - Recipients"], - "description": "**This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.**\n\nYou are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_recipient_count" - }, - "examples": { - "response": { - "value": { - "recipient_count": 1234 - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-recipients-billablecount", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/contactdb/recipients/count": { - "get": { - "operationId": "GET_contactdb-recipients-count", - "summary": "Retrieve a Count of Recipients", - "tags": ["Contacts API - Recipients"], - "description": "**This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_recipient_count" - }, - "examples": { - "response": { - "value": { - "recipient_count": 1234 - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-recipients-count", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/contactdb/recipients/search": { - "get": { - "operationId": "GET_contactdb-recipients-search", - "summary": "Search recipients", - "tags": ["Contacts API - Recipients"], - "description": "**This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.**\n\nfield_name:\n\n* is a variable that is substituted for your actual custom field name from your recipient.\n* Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200)\n* If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert\nyour epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to\nMon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through\nMon, 02 Feb 2015 23:59:59 GMT.", - "parameters": [ - { - "name": "{field_name}", - "in": "query", - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "$ref": "#/components/schemas/contactdb_recipient" - } - } - } - }, - "examples": { - "response": { - "value": { - "recipients": [ - { - "created_at": 1422313607, - "email": "jones@example.com", - "first_name": null, - "id": "YUBh", - "last_clicked": null, - "last_emailed": null, - "last_name": "Jones", - "last_opened": null, - "updated_at": 1422313790, - "custom_fields": [ - { - "id": 23, - "name": "pet", - "value": "Fluffy", - "type": "text" - } - ] - } - ] - } - } - } - } - } - }, - "400": { - "description": "\"\" : \"Returned if no search params are specified\"\n\"field\" : \"Returned if the provided field is invalid or does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "The following parameters are not custom fields or reserved fields: [{field_name}]" - }, - { - "message": "No search params are specified" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-recipients-search", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "post": { - "operationId": "POST_contactdb-recipients-search", - "summary": "Search recipients", - "tags": ["Contacts API - Recipients"], - "description": "

\n Search using segment conditions without actually creating a segment.\n Body contains a JSON object with conditions, a list of conditions as described below, and an optional list_id, which is a valid list ID for a list to limit the search on.\n

\n\n

\n Valid operators for create and update depend on the type of the field for which you are searching.\n

\n\n
    \n
  • Dates:\n
      \n
    • \"eq\", \"ne\", \"lt\" (before), \"gt\" (after)\n
        \n
      • You may use MM/DD/YYYY for day granularity or an epoch for second granularity.
        • \n
      \n
      • \n
    • \"empty\", \"not_empty\"
      • \n
    • \"is within\"\n \n
      • \n
    \n
    • \n
  • Text: \"contains\", \"eq\" (is - matches the full field), \"ne\" (is not - matches any field where the entire field is not the condition value), \"empty\", \"not_empty\"
    • \n
  • Numbers: \"eq\", \"lt\", \"gt\", \"empty\", \"not_empty\"
    • \n
  • Email Clicks and Opens: \"eq\" (opened), \"ne\" (not opened)
    • \n
\n\n

\n Field values must all be a string.\n

\n\n

\n Search conditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either clicks.campaign_identifier or opens.campaign_identifier.\n The condition value should be a string containing the id of a completed campaign.\n

\n\n

\n Search conditions list may contain multiple conditions, joined by an \"and\" or \"or\" in the \"and_or\" field.\n The first condition in the conditions list must have an empty \"and_or\", and subsequent conditions must all specify an \"and_or\".\n

", - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "list_id": { - "type": "integer", - "format": "int32" - }, - "conditions": { - "type": "array", - "description": "The conditions by which this segment should be created.", - "items": { - "$ref": "#/components/schemas/contactdb_segments_conditions" - } - } - }, - "required": ["list_id", "conditions"], - "example": { - "list_id": -27497588, - "conditions": [ - { - "and_or": "", - "field": "birthday", - "value": "01/12/1985", - "operator": "eq" - }, - { - "and_or": "", - "field": "birthday", - "value": "01/12/1985", - "operator": "eq" - }, - { - "and_or": "", - "field": "birthday", - "value": "01/12/1985", - "operator": "eq" - }, - { - "and_or": "", - "field": "birthday", - "value": "01/12/1985", - "operator": "eq" - } - ] - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "type": "object", - "properties": { - "created_at": { - "type": "integer" - }, - "email": { - "type": "string" - }, - "id": { - "type": "string" - }, - "last_emailed": { - "type": "integer" - }, - "last_clicked": { - "type": "integer" - }, - "last_opened": { - "type": "integer" - }, - "custom_fields": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "name": { - "type": "string" - }, - "value": { - "anyOf": [ - { - "type": "integer" - }, - { - "type": "string" - } - ] - }, - "type": { - "type": "string" - } - } - } - }, - "updated_at": { - "type": "integer" - }, - "first_name": { - "type": "string" - } - } - } - }, - "recipient_count": { - "type": "integer" - } - } - }, - "examples": { - "response": { - "value": { - "recipients": [ - { - "created_at": -27901208, - "email": "ut magna quis ipsum", - "id": "fugiat ad adipisicing ullamco", - "last_emailed": 21626657 - }, - { - "created_at": 17466400, - "email": "sunt irure", - "id": "et", - "last_clicked": -23135244, - "last_opened": -44593357, - "first_name": "est" - }, - { - "created_at": -34495329, - "email": "reprehenderit incididunt velit Lorem esse", - "id": "esse Ut ad dolore", - "last_clicked": 10164083, - "last_opened": 34443062 - }, - { - "created_at": -37030673, - "email": "amet deserunt fugiat voluptate", - "id": "et exercitation commodo id laborum", - "last_clicked": -10497425 - }, - { - "created_at": 3658435, - "email": "labore veniam", - "id": "ad pariatur esse", - "last_opened": -84227501, - "custom_fields": [ - { - "id": -5765608, - "name": "proident pariatur", - "value": "do in magna mollit", - "type": "dolore ut" - }, - { - "id": -31131201, - "name": "laborum mollit", - "value": 84434696, - "type": "veniam" - } - ], - "updated_at": -56455352, - "first_name": "Ut cupidatat nulla deserunt adipisicing", - "last_clicked": -52862671 - } - ], - "recipient_count": 65190677 - } - } - } - } - } - }, - "400": { - "description": "" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_contactdb-recipients-search", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/contactdb/custom_fields": { - "post": { - "operationId": "POST_contactdb-custom_fields", - "summary": "Create a Custom Field", - "tags": ["Contacts API - Custom Fields"], - "description": "**This endpoint allows you to create a custom field.**\n\n**You can create up to 120 custom fields.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "type": { - "type": "string" - } - }, - "example": { - "name": "pet", - "type": "text" - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_custom_field_with_id" - }, - "examples": { - "response": { - "value": { - "id": 1, - "name": "pet", - "type": "text" - } - } - } - } - } - }, - "400": { - "description": "\"\" : \"Returned if request body is invalid JSON\"\n\"type\" : \"Returned if custom field type is invalid or not provided\"\n\"name\" : \"Returned if custom field name is not provided\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "Returned if request body is invalid JSON" - }, - { - "field": "type", - "message": "Returned if custom field type is invalid or not provided" - }, - { - "field": "name", - "message": "Returned if custom field name is not provided" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_contactdb-customfields", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_contactdb-custom_fields", - "summary": "Retrieve all custom fields", - "tags": ["Contacts API - Custom Fields"], - "description": "**This endpoint allows you to retrieve all custom fields.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "List All Custom Fields response", - "type": "object", - "properties": { - "custom_fields": { - "type": "array", - "items": { - "$ref": "#/components/schemas/contactdb_custom_field_with_id" - } - } - }, - "required": ["custom_fields"] - }, - "examples": { - "response": { - "value": { - "custom_fields": [ - { - "id": 6234, - "name": "age", - "type": "number" - }, - { - "id": 6233, - "name": "country", - "type": "text" - }, - { - "id": 6235, - "name": "favorite_color", - "type": "text" - }, - { - "id": 6239, - "name": "fname", - "type": "text" - }, - { - "id": 6240, - "name": "lname", - "type": "text" - }, - { - "id": 49439, - "name": "pet", - "type": "text" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-customfields", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/contactdb/custom_fields/{custom_field_id}": { - "parameters": [ - { - "name": "custom_field_id", - "in": "path", - "description": "The ID of the custom field that you want to retrieve.", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "get": { - "operationId": "GET_contactdb-custom_fields-custom_field_id", - "summary": "Retrieve a Custom Field", - "tags": ["Contacts API - Custom Fields"], - "description": "**This endpoint allows you to retrieve a custom field by ID.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_custom_field_with_id" - }, - "examples": { - "response": { - "value": { - "id": 1, - "name": "pet", - "type": "text" - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "invalid id" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"custom_field_id\" : \"Returned if custom_field_id does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "Custom field ID does not exist" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-customfields-customfieldid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_contactdb-custom_fields-custom_field_id", - "summary": "Delete a Custom Field", - "tags": ["Contacts API - Custom Fields"], - "description": "**This endpoint allows you to delete a custom field by ID.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "202": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "message": "Custom Field delete is processing." - } - } - } - } - } - }, - "400": { - "description": "\"id\" : \"Returned if custom_field_id is not valid\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "Custom field in use by one or more segment conditions" - }, - { - "message": "Custom field ID does not exist" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"custom_field_id\" : \"Returned if custom_field_id does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "Custom field ID does not exist" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_contactdb-customfields-customfieldid", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/contactdb/reserved_fields": { - "get": { - "operationId": "GET_contactdb-reserved_fields", - "summary": "Retrieve reserved fields", - "tags": ["Contacts API - Custom Fields"], - "description": "**This endpoint allows you to list all fields that are reserved and can't be used for custom field names.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "reserved_fields": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "type": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "reserved_fields": [ - { - "name": "first_name", - "type": "text" - }, - { - "name": "last_name", - "type": "text" - }, - { - "name": "email", - "type": "text" - }, - { - "name": "created_at", - "type": "date" - }, - { - "name": "updated_at", - "type": "date" - }, - { - "name": "last_emailed", - "type": "date" - }, - { - "name": "last_clicked", - "type": "date" - }, - { - "name": "last_opened", - "type": "date" - }, - { - "name": "lists", - "type": "set" - }, - { - "name": "campaigns", - "type": "set" - }, - { - "name": "my_custom_field", - "type": "text" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-reservedfields", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/contactdb/segments": { - "post": { - "operationId": "POST_contactdb-segments", - "summary": "Create a Segment", - "tags": ["Contacts API - Segments"], - "description": "**This endpoint allows you to create a new segment.**\n\n\n Valid operators for create and update depend on the type of the field for which you are searching.\n\n**Dates**\n- \"eq\", \"ne\", \"lt\" (before), \"gt\" (after)\n - You may use MM/DD/YYYY for day granularity or an epoch for second granularity.\n- \"empty\", \"not_empty\"\n- \"is within\"\n - You may use an [ISO 8601 date format](https://en.wikipedia.org/wiki/ISO_8601) or the # of days.\n\n**Text**\n- \"contains\"\n- \"eq\" (is/equals - matches the full field)\n- \"ne\" (is not/not equals - matches any field where the entire field is not the condition value)\n- \"empty\"\n- \"not_empty\"\n\n**Numbers**\n- \"eq\" (is/equals)\n- \"lt\" (is less than)\n- \"gt\" (is greater than)\n- \"empty\"\n- \"not_empty\"\n\n**Email Clicks and Opens**\n- \"eq\" (opened)\n- \"ne\" (not opened)\n\nAll field values must be a string.\n\n\nConditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either `clicks.campaign_identifier` or `opens.campaign_identifier`.\nThe condition value should be a string containing the id of a completed campaign.\n\n\nThe conditions list may contain multiple conditions, joined by an \"and\" or \"or\" in the \"and_or\" field.\n\nThe first condition in the conditions list must have an empty \"and_or\", and subsequent conditions must all specify an \"and_or\".", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_segments" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_segments_with_id" - }, - "examples": { - "response": { - "value": { - "id": 1, - "name": "Last Name Miller", - "list_id": 4, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - }, - { - "field": "last_clicked", - "value": "01/02/2015", - "operator": "gt", - "and_or": "and" - }, - { - "field": "clicks.campaign_identifier", - "value": "513", - "operator": "eq", - "and_or": "or" - } - ], - "recipient_count": 0 - } - } - } - } - } - }, - "400": { - "description": "\"name\" : \"Returned if the name is not valid\"\n\"list_id\" : \"Returned if the list_id is not valid\"\n\"and_or\" : \"Returned if and_or and set value is not passed into the request body\"\n\"and_or\" : \"Returned if and_or is set on the only condition passed\"\n\"and_or\" : \"Returned if and_or is set on all conditions\"\n\"and_or\" : \"Returned if and_or is not set on more than one condition and less than all conditions\"\n\"operator\" : \"Returned if operator and set value is not passed into the request body\"\n\"value\" : \"Returned if value and set value is not passed into the request body\"\n\"field\" : \"Returned if field and set value is not passed into the request body\"\n\"\" : \"Returned if request body is not valid json\"\n\"\" : \"Returned if invalid value is passed into one of the request body parameters\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "request body is not valid json" - }, - { - "message": "invalid value is passed into one of the request body parameters" - }, - { - "field": "field", - "message": "field and set value is not passed into the request body" - }, - { - "field": "value", - "message": "value and set value is not passed into the request body" - }, - { - "field": "operator", - "message": "operator and set value is not passed into the request body" - }, - { - "field": "and_or", - "message": "and_or is not set on more than one condition and less than all conditions" - }, - { - "field": "and_or", - "message": "and_or is set on all conditions" - }, - { - "field": "and_or", - "message": "and_or is set on the only condition passed" - }, - { - "field": "and_or", - "message": "and_or and set value is not passed into the request body" - }, - { - "field": "list_id", - "message": "the list_id is not valid" - }, - { - "field": "name", - "message": "the name is not valid" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_contactdb-segments", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_contactdb-segments", - "summary": "Retrieve all segments", - "tags": ["Contacts API - Segments"], - "description": "**This endpoint allows you to retrieve all of your segments.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "List All Segments response", - "type": "object", - "properties": { - "segments": { - "type": "array", - "items": { - "$ref": "#/components/schemas/contactdb_segments" - } - } - }, - "required": ["segments"] - }, - "examples": { - "response": { - "value": { - "segments": [ - { - "id": 1234, - "name": "Age segments < 25", - "conditions": [ - { - "field": "age", - "value": "25", - "operator": "lt" - } - ], - "recipient_count": 8 - }, - { - "id": 2345, - "name": "email address - gmail", - "conditions": [ - { - "field": "email", - "value": "@gmail.com", - "operator": "contains" - } - ], - "recipient_count": 0 - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-segments", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/contactdb/segments/{segment_id}": { - "parameters": [ - { - "name": "segment_id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_contactdb-segments-segment_id", - "summary": "Retrieve a segment", - "tags": ["Contacts API - Segments"], - "description": "**This endpoint allows you to retrieve a single segment with the given ID.**", - "parameters": [ - { - "name": "segment_id", - "in": "query", - "description": "The ID of the segment you want to request.", - "required": true, - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_segments" - }, - "examples": { - "response": { - "value": { - "id": 1, - "name": "Last Name Miller", - "list_id": 4, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - } - ], - "recipient_count": 1 - } - } - } - } - } - }, - "400": { - "description": "\"segment_id\" : \"Returned if segment_id is not valid\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "if segment_id is not valid" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "segment_id not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-segments-segmentid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_contactdb-segments-segment_id", - "summary": "Update a segment", - "tags": ["Contacts API - Segments"], - "description": "**This endpoint allows you to update a segment.**", - "parameters": [ - { - "name": "segment_id", - "in": "query", - "description": "The ID of the segment you are updating.", - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "list_id": { - "type": "number", - "description": "The list ID you would like this segment to be built from." - }, - "conditions": { - "type": "array", - "description": "The conditions by which this segment should be created.", - "items": { - "$ref": "#/components/schemas/contactdb_segments_conditions" - } - } - }, - "required": ["name"], - "example": { - "name": "The Millers", - "list_id": 5, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - } - ] - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/contactdb_segments" - }, - "examples": { - "response": { - "value": { - "id": 5, - "name": "The Millers", - "list_id": 5, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - } - ], - "recipient_count": 1 - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "request body is not valid json" - }, - { - "message": "invalid value is passed into one of the request body parameters" - }, - { - "segment_id": "segment_id", - "message": "segment id is not valid" - }, - { - "field": "field", - "message": "field and set value is not passed into the request body" - }, - { - "field": "value", - "message": "value and set value is not passed into the request body" - }, - { - "field": "operator", - "message": "operator and set value is not passed into the request body" - }, - { - "field": "and_or", - "message": "and_or is not set on more than one condition and less than all conditions" - }, - { - "field": "and_or", - "message": "and_or is set on all conditions" - }, - { - "field": "and_or", - "message": "and_or is set on the only condition passed" - }, - { - "field": "and_or", - "message": "and_or and set value is not passed into the request body" - }, - { - "field": "list_id", - "message": "the list_id is not valid" - }, - { - "field": "name", - "message": "the name is not valid" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_contactdb-segments-segmentid", - "public": false, - "mock": { - "statusCode": 200, - "dynamic": false, - "enabled": false - } - } - }, - "delete": { - "operationId": "DELETE_contactdb-segments-segment_id", - "summary": "Delete a segment", - "tags": ["Contacts API - Segments"], - "description": "**This endpoint allows you to delete a segment from your recipients database.**\n\nYou also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment.", - "parameters": [ - { - "name": "delete_contacts", - "in": "query", - "description": "True to delete all contacts matching the segment in addition to deleting the segment", - "schema": { - "type": "boolean" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/DELETE_contactdb-lists-list_idBody" - }, - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "nullable": true - } - } - } - }, - "400": { - "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"delete_contacts\" : \"Returned if delete_contacts is not a valid boolean\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "segment_id", - "message": "Returned if segment_id is not valid" - }, - { - "field": "delete_contacts", - "message": "Returned if delete_contacts is not a valid boolean" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "segment_id", - "message": "segment_id does not exist" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_contactdb-segments-segmentid", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 204 - } - } - } - }, - "/contactdb/segments/{segment_id}/recipients": { - "parameters": [ - { - "name": "segment_id", - "in": "path", - "description": "The ID of the segment from which you want to retrieve recipients.", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "get": { - "operationId": "GET_contactdb-segments-segment_id-recipients", - "summary": "Retrieve recipients on a segment", - "tags": ["Contacts API - Segments"], - "description": "**This endpoint allows you to retrieve all of the recipients in a segment with the given ID.**", - "parameters": [ - { - "name": "page", - "in": "query", - "schema": { - "type": "integer" - } - }, - { - "name": "page_size", - "in": "query", - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "List Recipients On a Segment response", - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "$ref": "#/components/schemas/contactdb_recipient" - } - } - }, - "required": ["recipients"] - }, - "examples": { - "response": { - "value": { - "recipients": [ - { - "created_at": 1422313607, - "email": "jones@example.com", - "first_name": null, - "id": "YUBh", - "last_clicked": null, - "last_emailed": null, - "last_name": "Jones", - "last_opened": null, - "updated_at": 1422313790, - "custom_fields": [ - { - "id": 23, - "name": "pet", - "value": "Indiana", - "type": "text" - } - ] - } - ] - } - } - } - } - } - }, - "400": { - "description": "\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"segment_id\" : \"Returned if segment_id does not exist\"", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_contactdb-segments-segmentid-recipients", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/categories": { - "get": { - "operationId": "GET_categories", - "summary": "Retrieve all categories", - "tags": ["Categories"], - "description": "**This endpoint allows you to retrieve a list of all of your categories.**", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of categories to display per page.", - "schema": { - "type": "integer", - "default": 50 - } - }, - { - "name": "category", - "in": "query", - "description": "Allows you to perform a prefix search on this particular category.", - "schema": { - "type": "string" - } - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list that you would like to begin displaying results.", - "schema": { - "type": "integer", - "default": 0 - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "category": { - "type": "string", - "description": "A category used to group emails by broad topic." - } - }, - "required": ["category"] - } - }, - "examples": { - "response": { - "value": [ - { - "category": "category 1" - }, - { - "category": "category 2" - } - ] - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The error returned.", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string", - "description": "A message explaining why your categories could not be retrieved." - } - }, - "required": ["field", "message"] - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "sort_by", - "message": "invalid sort value" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_categories", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/categories/stats/sums": { - "get": { - "operationId": "GET_categories-stats-sums", - "summary": "Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]", - "tags": ["Categories"], - "description": "**This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.", - "parameters": [ - { - "name": "sort_by_metric", - "in": "query", - "description": "The metric that you want to sort by. Must be a single metric.", - "required": false, - "schema": { - "type": "string", - "default": "delivered" - } - }, - { - "name": "sort_by_direction", - "in": "query", - "description": "The direction you want to sort.", - "required": false, - "schema": { - "type": "string", - "enum": ["desc", "asc"], - "default": "desc" - } - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "limit", - "in": "query", - "description": "Limits the number of results returned.", - "required": false, - "schema": { - "type": "integer", - "default": 5 - } - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list to begin retrieving results.", - "required": false, - "schema": { - "type": "integer", - "default": 0 - } - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "schema": { - "type": "string", - "enum": ["day", "week", "month"] - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/category_stats" - }, - "examples": { - "response": { - "value": { - "date": "2015-01-01", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 20, - "deferred": 0, - "delivered": 20, - "invalid_emails": 0, - "opens": 20, - "processed": 0, - "requests": 20, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 20, - "unique_opens": 20, - "unsubscribe_drops": 0, - "unsubscribes": 20 - }, - "name": "cat1", - "type": "category" - }, - { - "metrics": { - "blocks": 1, - "bounce_drops": 0, - "bounces": 0, - "clicks": 19, - "deferred": 0, - "delivered": 19, - "invalid_emails": 0, - "opens": 19, - "processed": 0, - "requests": 20, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 19, - "unique_opens": 19, - "unsubscribe_drops": 0, - "unsubscribes": 19 - }, - "name": "cat2", - "type": "category" - }, - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 5, - "deferred": 0, - "delivered": 5, - "invalid_emails": 0, - "opens": 5, - "processed": 0, - "requests": 5, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 5, - "unique_opens": 5, - "unsubscribe_drops": 0, - "unsubscribes": 5 - }, - "name": "cat3", - "type": "category" - }, - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 6, - "deferred": 0, - "delivered": 5, - "invalid_emails": 0, - "opens": 6, - "processed": 0, - "requests": 5, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 5, - "unique_opens": 5, - "unsubscribe_drops": 0, - "unsubscribes": 6 - }, - "name": "cat4", - "type": "category" - }, - { - "metrics": { - "blocks": 10, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 10, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "cat5", - "type": "category" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_categories-stats-sums", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/categories/stats": { - "get": { - "operationId": "GET_categories-stats", - "summary": "Retrieve Email Statistics for Categories", - "tags": ["Categories"], - "description": "**This endpoint allows you to retrieve all of your email statistics for each of your categories.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.", - "parameters": [ - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "categories", - "in": "query", - "description": "The individual categories that you want to retrieve statistics for. You may include up to 10 different categories.", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "limit", - "in": "query", - "description": "The number of results to include.", - "required": false, - "schema": { - "type": "integer", - "maximum": 500, - "default": 500 - } - }, - { - "name": "offset", - "in": "query", - "description": "The number of results to skip.", - "required": false, - "schema": { - "type": "integer" - } - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "schema": { - "type": "string", - "enum": ["day", "week", "month"] - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/category_stats" - } - }, - "examples": { - "response": { - "value": [ - { - "date": "2015-10-01", - "stats": [ - { - "type": "category", - "name": "docs", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - }, - { - "type": "category", - "name": "mattscategory", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "category", - "name": "docs", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - }, - { - "type": "category", - "name": "mattscategory", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_categories-stats", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/campaigns": { - "post": { - "operationId": "POST_campaigns", - "summary": "Create a Campaign", - "tags": ["Campaigns API"], - "description": "**This endpoint allows you to create a campaign.**\n\nIn order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/campaign_request" - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/campaign_response" - }, - "examples": { - "response": { - "value": { - "id": 986724, - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [110, 124], - "segment_ids": [110], - "categories": ["spring line"], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our spring line!

", - "plain_content": "Check out our spring line!", - "status": "Draft" - } - } - } - } - } - }, - "400": { - "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\": \"You've reached your limit of 250 campaigns. Please delete one or more and try again.\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "title", - "message": "title can't be blank" - }, - { - "field": "title", - "message": "title is too long (maximum is 100 characters)" - }, - { - "field": "categories", - "message": "categories exceeds 10 category limit" - }, - { - "field": "html_content", - "message": "html_content exceeds the 1MB limit" - }, - { - "field": "plain_content", - "message": "plain_content exceeds the 1MB limit" - }, - { - "field": "sender_id", - "message": "sender_id does not exist" - }, - { - "field": "sender_id", - "message": "sender_id is not a verified sender identity" - }, - { - "field": "list_ids", - "message": "list_ids do not all exist" - }, - { - "field": "segment_ids", - "message": "segment_ids do not all exist" - }, - { - "field": "ip_pool", - "message": "The ip pool you provided is invalid" - }, - { - "field": "suppression_group_id", - "message": "suppression_group_id does not exist" - }, - { - "field": "unsubscribes", - "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - }, - { - "field": null, - "message": "You've reached your limit of 250 campaigns. Please delete one or more and try again." - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_campaigns", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_campaigns", - "summary": "Retrieve all Campaigns", - "tags": ["Campaigns API"], - "description": "**This endpoint allows you to retrieve a list of all of your campaigns.**\n\nReturns campaigns in reverse order they were created (newest first).\n\nReturns an empty array if no campaigns exist.", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of results you would like to receive at a time.", - "schema": { - "type": "integer", - "default": 10 - } - }, - { - "name": "offset", - "in": "query", - "description": "The index of the first campaign to return, where 0 is the first campaign.", - "schema": { - "type": "integer", - "default": 0 - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/components/schemas/campaign_response" - } - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "id": 986724, - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [110, 124], - "segment_ids": [110], - "categories": ["spring line"], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our spring line!

", - "plain_content": "Check out our spring line!", - "status": "Draft" - }, - { - "id": 986723, - "title": "February Newsletter", - "subject": "Final Winter Product Sale!", - "sender_id": 124451, - "list_ids": [110, 124], - "segment_ids": [110], - "categories": ["winter line"], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Last call for winter clothes!

", - "plain_content": "Last call for winter clothes!", - "status": "Sent" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_campaigns", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/campaigns/{campaign_id}": { - "parameters": [ - { - "name": "campaign_id", - "in": "path", - "description": "The id of the campaign you would like to retrieve.", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "get": { - "operationId": "GET_campaigns-campaign_id", - "summary": "Retrieve a single campaign", - "tags": ["Campaigns API"], - "description": "**This endpoint allows you to retrieve a specific campaign.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "categories": { - "type": "array", - "items": { - "type": "string" - } - }, - "custom_unsubscribe_url": { - "type": "string" - }, - "html_content": { - "type": "string" - }, - "id": { - "type": "integer" - }, - "ip_pool": { - "type": "string" - }, - "list_ids": { - "type": "array", - "items": { - "type": "integer" - } - }, - "plain_content": { - "type": "string" - }, - "segment_ids": { - "type": "array", - "items": { - "type": "integer" - } - }, - "sender_id": { - "type": "integer" - }, - "status": { - "type": "string" - }, - "subject": { - "type": "string" - }, - "suppression_group_id": { - "type": "integer" - }, - "title": { - "type": "string" - } - } - }, - "examples": { - "response": { - "value": { - "categories": ["spring line"], - "custom_unsubscribe_url": "", - "html_content": "

Check out our spring line!

", - "id": 986724, - "ip_pool": "marketing", - "list_ids": [110], - "plain_content": "Check out our spring line!", - "segment_ids": [110], - "sender_id": 124451, - "status": "Draft", - "subject": "New Products for Spring!", - "suppression_group_id": 42, - "title": "March Newsletter" - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "content": { - "application/json": { - "schema": { - "type": "object" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_campaigns-campaignid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_campaigns-campaign_id", - "summary": "Delete a Campaign", - "tags": ["Campaigns API"], - "description": "**This endpoint allows you to delete a specific campaign.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "nullable": true - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_campaigns-campaignid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_campaigns-campaign_id", - "summary": "Update a Campaign", - "tags": ["Campaigns API"], - "description": "**This endpoint allows you to update a specific campaign.**\n\nThis is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "title": "Update a Campaign request", - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The title of the campaign." - }, - "subject": { - "type": "string", - "description": "The subject line for your campaign." - }, - "categories": { - "type": "array", - "description": "The categories you want to tag on this campaign.", - "items": { - "type": "string" - } - }, - "html_content": { - "type": "string", - "description": "The HTML content of this campaign." - }, - "plain_content": { - "type": "string", - "description": "The plain content of this campaign." - } - }, - "required": ["title", "subject", "categories", "html_content", "plain_content"], - "example": { - "title": "May Newsletter", - "subject": "New Products for Summer!", - "categories": ["summer line"], - "html_content": "

Check out our summer line!

", - "plain_content": "Check out our summer line!" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/campaign_response" - }, - "examples": { - "response": { - "value": { - "id": 986724, - "title": "May Newsletter", - "subject": "New Products for Summer!", - "sender_id": 124451, - "list_ids": [110, 124], - "segment_ids": [110], - "categories": ["summer line"], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our summer line!

", - "plain_content": "Check out our summer line!", - "status": "Draft" - } - } - } - } - } - }, - "400": { - "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"", - "content": { - "application/json": { - "schema": { - "type": "object" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "title", - "message": "title can't be blank" - }, - { - "field": "title", - "message": "title is too long (maximum is 100 characters)" - }, - { - "field": "categories", - "message": "categories exceeds 10 category limit" - }, - { - "field": "html_content", - "message": "html_content exceeds the 1MB limit" - }, - { - "field": "plain_content", - "message": "plain_content exceeds the 1MB limit" - }, - { - "field": "sender_id", - "message": "sender_id does not exist" - }, - { - "field": "sender_id", - "message": "sender_id is not a verified sender identity" - }, - { - "field": "list_ids", - "message": "list_ids do not all exist" - }, - { - "field": "segment_ids", - "message": "segment_ids do not all exist" - }, - { - "field": "ip_pool", - "message": "The ip pool you provided is invalid" - }, - { - "field": "suppression_group_id", - "message": "suppression_group_id does not exist" - }, - { - "field": "unsubscribes", - "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "403": { - "description": "\"\": \"You may only update a campaign when it is in draft mode.\"", - "content": { - "application/json": { - "schema": { - "type": "object" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "You may only update a campaign when it is in draft mode." - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_campaigns-campaignid", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/campaigns/{campaign_id}/schedules/now": { - "parameters": [ - { - "name": "campaign_id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "post": { - "operationId": "POST_campaigns-campaign_id-schedules-now", - "summary": "Send a Campaign", - "tags": ["Campaigns API"], - "description": "**This endpoint allows you to immediately send an existing campaign.**\n\nNormally a POST request would have a body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "Send a Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "status": { - "type": "string" - } - }, - "required": ["id", "status"] - }, - "examples": { - "response": { - "value": { - "id": 1234, - "status": "Scheduled" - } - } - } - } - } - }, - "400": { - "description": "\"subject\": \"subject can't be blank\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "subject", - "message": "subject can't be blank" - }, - { - "field": "sender_id", - "message": "sender_id can't be blank" - }, - { - "field": "plain_content", - "message": "plain_content can't be blank, please provide plain text or html content" - }, - { - "field": "list_id", - "message": "You must select at least 1 segment or 1 list to send to." - }, - { - "field": "unsubscribe_tag", - "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - }, - { - "field": "suppression_group_id", - "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "403": { - "description": "\"\": \"You may only send a campaign when it is in draft mode.\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "You may only send a campaign when it is in draft mode." - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_campaigns-campaignid-schedules-now", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/campaigns/{campaign_id}/schedules": { - "parameters": [ - { - "name": "campaign_id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "post": { - "operationId": "POST_campaigns-campaign_id-schedules", - "summary": "Schedule a Campaign", - "tags": ["Campaigns API"], - "description": "**This endpoint allows you to schedule a specific date and time for your campaign to be sent.**\n\nIf you have the flexibility, it's better to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour. Scheduling email to avoid those times (for example, scheduling at 10:53) can result in lower deferral rates because it won't be going through our servers at the same times as everyone else's mail.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "title": "Schedule a Campaign request", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "description": "The unix timestamp for the date and time you would like your campaign to be sent out." - } - }, - "required": ["send_at"], - "example": { - "send_at": 1489771528 - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "Schedule a Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The campaign ID." - }, - "send_at": { - "type": "integer", - "description": "The date time you scheduled your campaign to be sent." - }, - "status": { - "type": "string", - "description": "The status of your campaign.", - "enum": ["Scheduled"] - } - }, - "required": ["id", "send_at", "status"] - }, - "examples": { - "response": { - "value": { - "id": 1234, - "send_at": 1489771528, - "status": "Scheduled" - } - } - } - } - } - }, - "400": { - "description": "\"subject\": \"subject can't be blank\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\":\"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "subject", - "message": "subject can't be blank" - }, - { - "field": "sender_id", - "message": "sender_id can't be blank" - }, - { - "field": "plain_content", - "message": "plain_content can't be blank, please provide plain text or html content" - }, - { - "field": "list_id", - "message": "You must select at least 1 segment or 1 list to send to." - }, - { - "field": "unsubscribe_tag", - "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - }, - { - "field": "suppression_group_id", - "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - }, - "403": { - "description": "\"\": \"You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH.\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH." - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_campaigns-campaignid-schedules", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_campaigns-campaign_id-schedules", - "summary": "Update a Scheduled Campaign", - "tags": ["Campaigns API"], - "description": "**This endpoint allows to you change the scheduled time and date for a campaign to be sent.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "title": "Update a Scheduled Campaign request", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "format": "int64" - } - }, - "required": ["send_at"], - "example": { - "send_at": 1489451436 - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "Update a Scheduled Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The campaign ID" - }, - "send_at": { - "type": "integer", - "description": "The unix timestamp to send the campaign." - }, - "status": { - "type": "string", - "description": "The status of the schedule." - } - }, - "required": ["id", "send_at", "status"] - } - } - } - }, - "400": { - "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"\":\"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "send_at", - "message": "Please choose a future time for sending your campaign." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing" - } - ] - } - } - } - } - } - }, - "403": { - "description": "\"send_at\": \"You cannot update the send_at value of non-scheduled campaign.\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "send_at", - "message": "You cannot update the send_at value of non-scheduled campaign." - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_campaigns-campaignid-schedules", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_campaigns-campaign_id-schedules", - "summary": "View Scheduled Time of a Campaign", - "tags": ["Campaigns API"], - "description": "**This endpoint allows you to retrieve the date and time that a campaign has been scheduled to be sent.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "View Scheduled Time of a Campaign response", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "format": "int64" - } - }, - "required": ["send_at"] - }, - "examples": { - "response": { - "value": { - "send_at": 1490778528 - } - } - } - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_campaigns-campaignid-schedules", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_campaigns-campaign_id-schedules", - "summary": "Unschedule a Scheduled Campaign", - "tags": ["Campaigns API"], - "description": "**This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.**\n\nA successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is to cancel (a different method).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "nullable": true - } - } - } - }, - "403": { - "description": "\"\": \"This campaign is already In Progress.\"\n\"\": \"This campaign is already Sent.\"\n\"\": \"This campaign is already Paused.\"\n\"\": \"This campaign is already Canceled.\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "This campaign is already In Progress." - }, - { - "field": null, - "message": "This campaign is already Sent." - }, - { - "field": null, - "message": "This campaign is already Paused." - }, - { - "field": null, - "message": "This campaign is already Canceled." - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_campaigns-campaignid-schedules", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/campaigns/{campaign_id}/schedules/test": { - "parameters": [ - { - "name": "campaign_id", - "in": "path", - "required": true, - "schema": { - "type": "integer" - } - } - ], - "post": { - "operationId": "POST_campaigns-campaign_id-schedules-test", - "summary": "Send a Test Campaign", - "tags": ["Campaigns API"], - "description": "**This endpoint allows you to send a test campaign.**\n\nTo send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "to": { - "type": "string", - "description": "The email address that should receive the test campaign.", - "format": "email" - } - }, - "required": ["to"], - "example": { - "to": "your.email@example.com" - } - } - } - } - }, - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "Send a Test Campaign request", - "type": "object", - "properties": { - "to": { - "type": "string" - } - }, - "required": ["to"] - } - } - } - }, - "400": { - "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"to\": \"Please provide an email address to which the test should be sent.\"\n\"to\": \"You can only send tests to 10 addresses at a time.\"\n\"subject\": \"Please add a subject to your campaign before sending a test.\"\n\"plain_content\": \"Plain content and html content can't both be blank. Please set one of these values before sending a test.\"\n\"sender_id\": \"Please assign a sender identity to your campaign before sending a test.\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": "send_at", - "message": "Please choose a future time for sending your campaign." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - } - ] - } - } - } - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_campaigns-campaignid-schedules-test", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/templates": { - "post": { - "operationId": "POST_templates", - "summary": "Create a transactional template.", - "tags": ["Transactional Templates"], - "description": "**This endpoint allows you to create a transactional template.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name for the new transactional template.", - "maxLength": 100 - }, - "generation": { - "type": "string", - "description": "Defines whether the template supports dynamic replacement.", - "enum": ["legacy", "dynamic"], - "default": "legacy" - } - }, - "required": ["name"], - "example": { - "name": "example_name", - "generation": "dynamic" - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/transactional_template" - }, - "examples": { - "response": { - "value": { - "id": "733ba07f-ead1-41fc-933a-3976baa23716", - "name": "example_name", - "generation": "legacy", - "updated_at ": "2021-04-28 13:12:46", - "versions": [] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_templates", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_templates", - "summary": "Retrieve paged transactional templates.", - "tags": ["Transactional Templates"], - "description": "**This endpoint allows you to retrieve all transactional templates.**", - "parameters": [ - { - "name": "generations", - "in": "query", - "description": "Comma-delimited list specifying which generations of templates to return. Options are `legacy`, `dynamic` or `legacy,dynamic`.", - "required": false, - "schema": { - "type": "string", - "enum": ["legacy", "dynamic", "legacy,dynamic"], - "default": "legacy" - } - }, - { - "name": "page_size", - "in": "query", - "description": "The number of templates to be returned in each page of results", - "required": true, - "schema": { - "type": "number", - "minimum": 1, - "maximum": 200 - } - }, - { - "name": "page_token", - "in": "query", - "description": "A token corresponding to a specific page of results, as provided by metadata", - "required": false, - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "", - "items": { - "$ref": "#/components/schemas/transactional-templates-template-lean" - } - }, - "_metadata": { - "$ref": "#/components/schemas/_metadata" - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "id": "fae7c985-eb92-4b47-9987-28ec29dbc698", - "name": "example_name", - "generation": "legacy", - "updated_at ": "2020-11-12 12:00:09", - "versions": [] - } - ], - "_metadata": { - "self": "https://api.sendgrid.com/v3/templates", - "count": 1 - } - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "": { - "type": "string" - }, - "message": { - "type": "string" - }, - "error_id": { - "type": "string" - } - } - } - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_templates", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/templates/{template_id}": { - "parameters": [ - { - "name": "template_id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "post": { - "operationId": "POST_templates-template_id", - "summary": "Duplicate a transactional template.", - "tags": ["Transactional Templates"], - "description": "**This endpoint allows you to duplicate a transactional template.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name for the new transactional template.", - "maxLength": 100 - } - }, - "example": { - "name": "example_name" - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/transactional_template" - }, - "examples": { - "response": { - "value": { - "id": "733ba07f-ead1-41fc-933a-3976baa23716", - "name": "example_name", - "generation": "dynamic", - "updated_at ": "2020-12-12 58:26:65", - "versions": [] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_templates-templateid", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_templates-template_id", - "summary": "Retrieve a single transactional template.", - "tags": ["Transactional Templates"], - "description": "**This endpoint allows you to retrieve a single transactional template.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/transactional_template" - }, - "examples": { - "response": { - "value": { - "id": "40da60e6-66f3-4223-9406-ba58b7f55a62", - "name": "Duis in dolor", - "generation": "legacy", - "updated_at ": "2020-12-12 58:26:65", - "versions": [] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_templates-templateid", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_templates-template_id", - "summary": "Edit a transactional template.", - "tags": ["Transactional Templates"], - "description": "**This endpoint allows you to edit the name of a transactional template.**\n\nTo edit the template itself, [create a new transactional template version](https://sendgrid.api-docs.io/v3.0/transactional-templates-versions/create-a-new-transactional-template-version).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the transactional template.", - "maxLength": 100 - } - }, - "example": { - "name": "new_example_name" - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/transactional_template" - }, - "examples": { - "response": { - "value": { - "id": "733ba07f-ead1-41fc-933a-3976baa23716", - "name": "new_example_name", - "generation": "legacy", - "updated_at ": "2021-04-28 13:12:46", - "versions": [] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_templates-templateid", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_templates-template_id", - "summary": "Delete a template.", - "tags": ["Transactional Templates"], - "description": "**This endpoint allows you to delete a transactional template.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_templates-templateid", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/templates/{template_id}/versions": { - "parameters": [ - { - "name": "template_id", - "in": "path", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "post": { - "operationId": "POST_templates-template_id-versions", - "summary": "Create a new transactional template version.", - "tags": ["Transactional Templates Versions"], - "description": "**This endpoint allows you to create a new version of a template.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/transactional_template_version_create" - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/transactional_template_version_output" - }, - "examples": { - "response": { - "value": { - "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", - "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", - "active": 1, - "name": "example_version_name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "generate_plain_content": true, - "subject": "<%subject%>", - "updated_at": "2019-03-13 18:56:33", - "editor": "code" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_templates-templateid-versions", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/templates/{template_id}/versions/{version_id}/activate": { - "parameters": [ - { - "name": "template_id", - "in": "path", - "description": "The ID of the original template", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "version_id", - "in": "path", - "description": "The ID of the template version", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "post": { - "operationId": "POST_templates-template_id-versions-version_id-activate", - "summary": "Activate a transactional template version.", - "tags": ["Transactional Templates Versions"], - "description": "**This endpoint allows you to activate a version of one of your templates.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/transactional_template_version_output" - }, - "examples": { - "response": { - "value": { - "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", - "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", - "active": 1, - "name": "example_version_name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "generate_plain_content": true, - "subject": "<%subject%>", - "updated_at": "2019-03-13 18:56:33", - "editor": "code" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_templates-templateid-versions-versionid-activate", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/templates/{template_id}/versions/{version_id}": { - "parameters": [ - { - "name": "template_id", - "in": "path", - "description": " The ID of the original template", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - }, - { - "name": "version_id", - "in": "path", - "description": "The ID of the template version", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "get": { - "operationId": "GET_templates-template_id-versions-version_id", - "summary": "Retrieve a specific transactional template version.", - "tags": ["Transactional Templates Versions"], - "description": "**This endpoint allows you to retrieve a specific version of a template.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/transactional_template_version_output" - }, - "examples": { - "response": { - "value": { - "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", - "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", - "active": 1, - "name": "example_version_name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "generate_plain_content": true, - "subject": "<%subject%>", - "updated_at": "2019-03-13 18:56:33", - "editor": "code" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_templates-templateid-versions-versionid", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_templates-template_id-versions-version_id", - "summary": "Edit a transactional template version.", - "tags": ["Transactional Templates Versions"], - "description": "**This endpoint allows you to edit the content of your template version.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/transactional_template_version_create" - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/transactional_template_version_output" - }, - "examples": { - "response": { - "value": { - "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", - "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", - "active": 1, - "name": "example_version_name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "generate_plain_content": true, - "subject": "<%subject%>", - "updated_at": "2019-03-13 18:56:33", - "editor": "code" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_templates-templateid-versions-versionid", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 200 - } - } - }, - "delete": { - "operationId": "DELETE_templates-template_id-versions-version_id", - "summary": "Delete a transactional template version.", - "tags": ["Transactional Templates Versions"], - "description": "**This endpoint allows you to delete a transactional template version.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_templates-templateid-versions-versionid", - "public": true, - "mock": { - "statusCode": 200, - "dynamic": false, - "enabled": false - } - } - } - }, - "/user/webhooks/event/settings": { - "get": { - "operationId": "GET_user-webhooks-event-settings", - "summary": "Retrieve Event Webhook settings", - "tags": ["Webhooks"], - "description": "**This endpoint allows you to retrieve your current event webhook settings.**\n\nIf an event type is marked as `true`, then the event webhook will include information about that event.\n\nSendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.\n\nCommon uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/event-webhook-response" - }, - "examples": { - "response": { - "value": { - "enabled": false, - "url": "incididunt reprehenderit", - "group_resubscribe": false, - "delivered": false, - "group_unsubscribe": false, - "spam_report": false, - "bounce": false, - "deferred": false, - "unsubscribe": true, - "processed": false, - "open": true, - "click": true, - "dropped": true, - "oauth_client_id": "est fugiat", - "oauth_token_url": "Duis in laborum sunt" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-webhooks-event-settings", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_user-webhooks-event-settings", - "summary": "Update Event Notification Settings", - "tags": ["Webhooks"], - "description": "**This endpoint allows you to update your current event webhook settings.**\n\nIf an event type is marked as `true`, then the event webhook will include information about that event.\n\nSendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.\n\nCommon uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/event-webhook-update-oauth-request" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/event-webhook-response" - }, - "examples": { - "response": { - "value": { - "enabled": true, - "url": "mollit laborum", - "group_resubscribe": false, - "delivered": true, - "group_unsubscribe": true, - "spam_report": true, - "bounce": true, - "deferred": true, - "unsubscribe": true, - "processed": true, - "open": true, - "click": false, - "dropped": true, - "oauth_client_id": "anim sunt", - "oauth_token_url": "ex" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_user-webhooks-event-settings", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/user/webhooks/parse/settings": { - "get": { - "operationId": "GET_user-webhooks-parse-settings", - "summary": "Retrieve all parse settings", - "tags": ["Webhooks"], - "description": "**This endpoint allows you to retrieve all of your current inbound parse settings.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "The list of your current inbound parse settings.", - "items": { - "$ref": "#/components/schemas/parse-setting" - } - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "url": "http://mydomain.com/parse", - "hostname": "mail.mydomain.com", - "spam_check": true, - "send_raw": true - } - ] - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-webhooks-parse-settings", - "public": true, - "mock": { - "dynamic": false, - "statusCode": 200, - "enabled": false - } - } - }, - "post": { - "operationId": "POST_user-webhooks-parse-settings", - "summary": "Create a parse setting", - "tags": ["Settings - Inbound Parse"], - "description": "**This endpoint allows you to create a new inbound parse setting.**\n\nCreating an Inbound Parse setting requires two pieces of information: a `url` and a `hostname`.\n\nThe `hostname` must correspond to a domain authenticated by Twilio SendGrid on your account. If you need to complete domain authentication, you can use the [Twilio SendGrid App](https://app.sendgrid.com/settings/sender_auth) or the \"Authenticate a domain\" endpoint. See \"[How to Set Up Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/)\" for instructions.\n\nAny email received by the `hostname` will be parsed when you complete this setup. You must also add a Twilio SendGrid MX record to this domain's DNS records. See \"[Setting up the Inbound Parse Webhook](https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/)\" for full instructions.\n\nThe `url` represents a location where the parsed message data will be delivered. Twilio SendGrid will make an HTTP POST request to this `url` with the message data. The `url` must be publicly reachable, and your application must return a `200` status code to signal that the message data has been received.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/parse-setting" - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/parse-setting" - }, - "examples": { - "response": { - "value": { - "url": "http://email.myhostname.com", - "hostname": "myhostname.com", - "spam_check": false, - "send_raw": true - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_user-webhooks-parse-settings", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/user/webhooks/parse/stats": { - "get": { - "operationId": "GET_user-webhooks-parse-stats", - "summary": "Retrieves Inbound Parse Webhook statistics.", - "tags": ["Webhooks"], - "description": "**This endpoint allows you to retrieve the statistics for your Parse Webhook useage.**\n\nSendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incomming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 30MB in size, including all attachments.\n\nThere are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the [Library Index](https://sendgrid.com/docs/Integrate/libraries.html#-Webhook-Libraries).", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of statistics to return on each page.", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "offset", - "in": "query", - "description": "The number of statistics to skip.", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How you would like the statistics to by grouped. ", - "required": false, - "schema": { - "type": "string", - "enum": ["day", "week", "month"] - } - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD", - "required": false, - "schema": { - "type": "string", - "default": "The day the request is made." - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the stats were collected." - }, - "stats": { - "type": "array", - "description": "The Parse Webhook usage statistics.", - "items": { - "type": "object", - "properties": { - "metrics": { - "type": "object", - "properties": { - "received": { - "type": "number", - "description": "The number of emails received and parsed by the Parse Webhook." - } - }, - "required": ["received"] - } - } - } - } - }, - "required": ["date", "stats"] - } - }, - "examples": { - "response": { - "value": [ - { - "date": "2015-10-11", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-17", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-25", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-26", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-28", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-29", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-30", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-31", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-02", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-03", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-10", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-webhooks-parse-stats", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/user/webhooks/event/settings/signed": { - "get": { - "operationId": "GET_user-webhooks-event-settings-signed", - "summary": "Retrieve Signed Webhook Public Key", - "tags": ["Webhooks"], - "description": "**This endpoint allows you to retrieve your signed webhook's public key.**\n\nOnce you have enabled signing of the Event Webhook, you will need the public key provided to verify the signatures on requests coming from Twilio SendGrid. You can retrieve the public key from this endpoint at any time.\n\nFor more information about cryptographically signing the Event Webhook, see [Getting Started with the Event Webhook Security Features](https://sendgrid.com/docs/for-developers/tracking-events/getting-started-event-webhook-security-features).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "public_key": { - "type": "string", - "description": "The public key you can use to verify the Twilio SendGrid signature." - } - }, - "required": ["public_key"] - }, - "examples": { - "response": { - "value": { - "public_key": "anim quis in sint" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-webhooks-event-settings-signed", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_user-webhooks-event-settings-signed", - "summary": "Enable/Disable Signed Webhook", - "tags": ["Webhooks"], - "description": "**This endpoint allows you to enable or disable signing of the Event Webhook.**\n\nThis endpoint takes a single boolean request parameter, `enabled`. You may either enable or disable signing of the Event Webhook using this endpoint. Once enabled, you can retrieve your public key using the `/webhooks/event/settings/signed` endpoint.\n\nFor more information about cryptographically signing the Event Webhook, see [Getting Started with the Event Webhook Security Features](https://sendgrid.com/docs/for-developers/tracking-events/getting-started-event-webhook-security-features).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } - }, - "required": ["enabled"], - "example": { - "enabled": true - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "public_key": { - "type": "string", - "description": "The public key you can use to verify the Twilio SendGrid signature." - } - }, - "required": ["public_key"] - }, - "examples": { - "response": { - "value": { - "public_key": "voluptate id Excepteur proident" - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "nullable": true, - "type": "string" - }, - "message": { - "type": "string" - } - }, - "required": ["message"] - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "mollit consequat dolore commodo", - "field": "anim Ut" - }, - { - "message": "qui" - }, - { - "message": "commodo dolor ipsum" - }, - { - "message": "minim fugiat amet", - "field": "quis consectetur eiusmod ullamco laboris" - } - ] - } - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "nullable": true, - "type": "string" - }, - "message": { - "type": "string" - } - }, - "required": ["message"] - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "fugiat", - "field": "in proident" - }, - { - "message": "adipisicing veniam laboris sunt ullamco", - "field": "ut" - }, - { - "message": "id sunt consequat Duis irure" - }, - { - "message": "nisi", - "field": "in qui" - }, - { - "message": "tempor in eiusmod elit" - } - ] - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "nullable": true, - "type": "string" - }, - "message": { - "type": "string" - } - }, - "required": ["message"] - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "Excepteur culpa esse ea ut" - }, - { - "message": "enim Excepteur dolore dolore" - }, - { - "message": "dolor occaecat" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_user-webhooks-event-settings-signed", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/user/webhooks/event/test": { - "post": { - "operationId": "POST_user-webhooks-event-test", - "summary": "Test Event Notification Settings", - "tags": ["Webhooks"], - "description": "**This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL.**\n\nSendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.\n\nCommon uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.\n\n>**Tip**: Retry logic for this endpoint differs from other endpoints, which use a rolling 24-hour retry.\n\nIf your web server does not return a 2xx response type, we will retry a POST request until we receive a 2xx response or the maximum time of 10 minutes has expired.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "url": { - "type": "string", - "description": "The URL where you would like the test notification to be sent." - }, - "oauth_client_id": { - "type": "string", - "description": "The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token. When passing data in this field, you must also include the oauth_client_secret and oauth_token_url fields." - }, - "oauth_client_secret": { - "type": "string", - "description": "This secret is needed only once to create an access token. SendGrid will store this secret, allowing you to update your Client ID and Token URL without passing the secret to SendGrid again. When passing data in this field, you must also include the oauth_client_id and oauth_token_url fields." - }, - "oauth_token_url": { - "type": "string", - "description": "The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider. When passing data in this field, you must also include the oauth_client_id and oauth_client_secret fields." - } - }, - "example": { - "url": "mollit non ipsum magna", - "oauth_client_id": "nisi", - "oauth_client_secret": "veniam commodo ex sunt", - "oauth_token_url": "dolor Duis" - } - } - } - } - }, - "responses": { - "204": { - "description": "" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_user-webhooks-event-test", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 200 - } - } - } - }, - "/messages": { - "get": { - "operationId": "GET-messages", - "summary": "Filter all messages", - "tags": ["Query", "Messages"], - "description": "This is **BETA** functionality. You may not have access, and we reserve the right to change functionality without notice.\n\nFilter all messages to search your Email Activity. All queries need to be [URL encoded](https://meyerweb.com/eric/tools/dencoder/), and have this format:\n\n`query={query_type}=\"{query_content}\"`\n\nencoded, this would look like this:\n\n`query=type%3D%22query_content%22`\n\nfor example:\n\nFilter by a specific email - `query=to_email%3D%22example%40example.com%22`\n\nFilter by subject line - `query=subject%3d%22A%20Great%20Subject%22`\n\n**Full list of basic query types and examples:**\n\n\n| **Filter query** | **Unencoded Example** (put this one into the try it out query - it'll automatically encode it for you) | **Encoded Example** (use this one in your code) |\n|-----------------|----------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------|\n| msg_id | msg_id=“filter0307p1las1-16816-5A023E36-1.0” | msg_id%3D%22filter0307p1las1-16816-5A023E36-1.0%22 |\n| from_email | from_email=“testing@sendgrid.net” | from_email%3D%22testing%40sendgrid.net%22 |\n| subject | subject=\"This is a subject test\" | subject%22This%20is%20a%20subject%20test%22 |\n| to_email | to_email=\"example@example.com\" | to_email%3D%22example%40example.com%22 |\n| status | | status%22processed%22 |\n| template_id | | |\n| asm_group_id | | |\n| api_key_id | | |\n| events | status=\"processed\" | status%3D%22processed%22 |\n| originating_ip | | |\n| categories | | |\n| unique_args | | |\n| outbound_ip | | |\n| last_event_time | last_event_time=“2017-11-07T23:13:58Z” | last_event_time%3D%E2%80%9C2017-11-07T23%3A13%3A58Z%E2%80%9D |\n| clicks | clicks=\"0\" | clicks%3D%220%22 |\n\nFor information about building compound queries, and for the full query language functionality, see the [query language reference](https://docs.google.com/a/sendgrid.com/document/d/1fWoKTFNfg5UUsB6t9KuIcSo9CetKF_T0bGfWJ_gdPCs/edit?usp=sharing).\n\nComing soon, example compound queries: limit + to email + date", - "parameters": [ - { - "name": "query", - "in": "query", - "description": "Use the query syntax to filter your email activity.", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "limit", - "in": "query", - "description": "The number of messages returned. This parameter must be greater than 0 and less than or equal to 1000", - "required": false, - "schema": { - "type": "number", - "minimum": 1, - "maximum": 1000, - "default": 10 - } - }, - { - "name": "X-Query-Id", - "in": "header", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "X-Cursor", - "in": "header", - "required": false, - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_authorizationHeader_Authorization" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "messages": { - "type": "array", - "items": { - "allOf": [ - { - "$ref": "#/components/schemas/email-activity-response-common-fields" - }, - { - "type": "object", - "properties": { - "opens_count": { - "type": "integer", - "description": "The number of times the message was opened." - }, - "clicks_count": { - "type": "integer", - "description": "The number of times links in the message were clicked." - }, - "last_event_time": { - "type": "string", - "description": "A timestamp of the last event received for the specific message in iso 8601 format." - } - } - } - ], - "title": "Abbv. Message", - "type": "object", - "properties": { - "from_email": { - "type": "string" - }, - "msg_id": { - "type": "string" - }, - "subject": { - "type": "string" - }, - "to_email": { - "type": "string" - }, - "status": { - "type": "string", - "enum": ["processed", "delivered", "not_delivered"] - }, - "opens_count": { - "type": "integer" - }, - "clicks_count": { - "type": "integer" - }, - "last_event_time": { - "type": "string", - "description": "iso 8601 format" - } - }, - "required": [ - "from_email", - "msg_id", - "subject", - "to_email", - "status", - "opens_count", - "clicks_count", - "last_event_time" - ], - "example": { - "from_email": "from@test.com", - "msg_id": "abc123", - "subject": "anim Duis sint veniam", - "to_email": "test@test.com", - "status": "processed", - "opens_count": 1, - "clicks_count": 2, - "last_event_time": "2017-10-13T18:56:21Z" - } - } - } - } - }, - "examples": { - "response": { - "value": { - "messages": [ - { - "from_email": "from@test.com", - "msg_id": "abc123", - "subject": "something profound", - "to_email": "to@test.com", - "status": "processed", - "opens_count": 0, - "clicks_count": 0, - "last_event_time": "2017-10-13T18:56:21Z", - "last_timestamp": 1495064728 - }, - { - "from_email": "yeah@test.com", - "msg_id": "321befe", - "subject": "something profound", - "to_email": "nah@test.com", - "status": "delivered", - "opens_count": 500, - "clicks_count": 200, - "last_event_time": "2017-10-13T18:56:21Z", - "last_timestamp": 1495064793 - }, - { - "from_email": "sad@test.com", - "msg_id": "434512dfg", - "subject": "something sad", - "to_email": "reject@test.com", - "status": "not_delivered", - "opens_count": 0, - "clicks_count": 0, - "last_event_time": "2017-10-13T18:56:21Z", - "last_timestamp": 1495064993 - } - ] - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - }, - "required": ["message"] - } - } - }, - "required": ["errors"] - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "invalid syntax: 'bad_field' is not a known field" - } - ] - } - } - } - } - } - }, - "429": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "too many requests" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET-messages", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/messages/{msg_id}": { - "parameters": [ - { - "name": "msg_id", - "in": "path", - "description": "The ID of the message you are requesting details for.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET-v3-messages-msg_id", - "summary": "Filter messages by message ID", - "tags": ["Query", "Messages"], - "description": "This is BETA functionality. You may not have access, and we reserve the right to change functionality without notice.\n\nGet all of the details about the specified message.", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/email-activity-response-common-fields" - }, - { - "type": "object", - "example": { - "from_email": "jane_doe@example.com", - "msg_id": "in aliquip id aliqua", - "subject": "est incididunt adipisicing pariatur", - "to_email": "send@test.com", - "status": "not_delivered", - "template_id": "123e4567-e89b-12d3-a456-426655440000", - "asm_group_id": 11376349, - "teammate": "", - "api_key_id": "sdfsdfsdf123", - "originating_ip": "2.3.4.5", - "events": [ - { - "event_name": "bounced", - "processed": "2017-10-13T18:56:21Z", - "bounce_type": "soft", - "http_user_agent": "in tempor ex dolore est", - "mx_server": "quis proident", - "server_response": "some error message" - } - ], - "categories": ["hi", "bye"], - "unique_args": "{'key': 'value'}", - "outbound_ip": "1.2.3.4", - "outbound_ip_type": "dedicated" - }, - "properties": { - "template_id": { - "type": "string", - "description": "The ID associated with a Twilio SendGrid email template used to format the message." - }, - "asm_group_id": { - "type": "integer", - "minimum": 1, - "description": "The unsubscribe group associated with this email." - }, - "teammate": { - "type": "string", - "description": "Teammate's username", - "minLength": 0, - "maxLength": 64, - "pattern": "^$|^[A-Za-z0-9]+" - }, - "api_key_id": { - "type": "string", - "minLength": 3, - "maxLength": 50, - "pattern": "^[A-Za-z0-9]+", - "description": "The ID of the API Key used to authenticate the sending request for the message." - }, - "events": { - "type": "array", - "description": "List of events related to email message", - "items": { - "title": "Event", - "type": "object", - "example": { - "event_name": "bounced", - "processed": "2017-10-13T18:56:21Z", - "reason": "some reason", - "url": "http://3LX,MU}N=B8'd,K}>bEma{l~!ad%peIF}y>qHfLPWQ$l9b\\!6.1H?$Z9H\"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0\"Q/-4dV\"Yk3QGg[(O86=Pf\"e17K4'r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*ObEma{l~!ad%peIF}y>qHfLPWQ$l9b\\!6.1H?$Z9H\"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0\"Q/-4dV\"Yk3QGg[(O86=Pf\"e17K4'r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*ObEma{l~!ad%peIF}y>qHfLPWQ$l9b\\!6.1H?$Z9H\"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0\"Q/-4dV\"Yk3QGg[(O86=Pf\"e17K4'r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*O0OiStFG.ZoRi2=j%fUVa]&re6k{hKqD-8vWE12Fb5JC6z>S@@'cWS~w5KtuIwv$8/JDD94CXx1n5yjC_I2lQ66zDj4MXe/4bqlcqqQ7evnQWTYx5roaEYMapyuzb/USpsyalh/HcYc9PmQfF8ND_C7bXnwFQ_fb_BHMXbIV8JN28/NjZdawDJ6kSWxLykSVTHzcISGPBRfs_rt3Uc65Vzj6LDSSMN8WRs70m0tAWs/fkDvjvm_7ZeV08YZeB9j9mS9BcE089Fn5UzDlTJW9vqDF5uipjlIVrNbM7oWE/MIJcjg2vJO20jA24WHrchrEXCvKcxriviSDl3tuyDxqdqRSekpm2aH6yW7_ylXj/nWsex4jm3rKvYw1uLq3Tp7qb9edhj8B_TnwLv1yjHSkgbA5jKI4BTqxugmwVTnFf2OFCFp/ZILLkoKgfwOyIK4reUIkhCjuhkwp/cqGaFAkeCFQXPB6DLYesLZ2M3KPuBsBrs3pr3HRbTtwaOzdKtGc8e0C0VTjrJ3GwljStMPrSuQWh6/vigHRasZ4P9kFv5DPVbHWZzPvtwUw0AMByt44YH678WpbAXXy4I/IVOHmErZTbw1mJ/3vd4uI5rr2zEO_YA9qJZLJT/wmBimbOyaMtmTNYr_FhgfkKMN3_1la7RCK8CIP3p26mbuHbdJV1j/5sTIKibInM5l2BoWdEi49bPqzagsfjKpGVbg0YQ8mjrLhI92/qy0eVYi34kBGVuLzxK2FLC8vwYUrbupjUYE23Mc_6nmHYRK1HF1QmZDZG1hw96I3MPbTZqeJOWGch230qDNxOgnHRNNM52k/3c7FeuRr88RwZGpif/4FaSAbdqkUNvJ9J9qX2tJS9x5vZlgD8k4YHIXDztrnwg2VPquj/uo_2MjbWybIF/NGJM2RFAsKV1S5iOejuTV4p12KlH1p0Dt5EpxCSIl0XoWuvyLYar77f_hzqNdWAyL0FDxGfj4ma4jwqdTTLNyeZEtguYoCHTFfY/HgJkpHx/yO23G7gLhKPvD459ceffHidFh7LipTxNF0GFXhIAPrWfhv7PkPmVofBoFFlo6/rMcHQ82d5VS8i1CCyLtfuT5WH9GqrsOY7xo3lxi7BNL93/PLRdQT3SObRFRERw68V5ZFvIuEQqFOFZQ848rWPLXYDGY658dyjZALf/Ug4EROi_ehNtzPwecer_RGBHxeMnpxrPAFZEL6YXNKzm8hh3HY4Uc4fgkjge5fXsR4CeTSkS66/FOD00deDKmN7XcHEj1LGlAmd4XlV8vFpXg2VazX4OLW8z6vXn5vntNGYO6eBCEKUwupRz9nQSMeZ/Pbmjoopyt6TxQBUfPkHBdgCIhqA1zDV72ARqGlK_ao9KVjvgbB98YeiieIyogkuOa4y0E5iUEdBopzovVgtY88yLijh9ww/tl0R5rI2P2_OxguTbv_wrfEm8jRjISEIqSE9q29RB3n8PeD4hu24rcsaEuTMCqniiLN0a2OtZiKxHnbsNB660Aq3/tEo2SHZBkkIFYXBbDNE7gLfvFz9ZaC_E2oV2quyK1Id5SkNkJBVRRgROWBc_XEOXktc4vRUKxy1MQ526Xilyo8/uI67lHH1Vlr4V3GVmweT4A16KMqzmVzvRDRFLpkBv2iu3Okc1vIqkC/426aOqeUm6SXIx16d8BWVRcmqKqizxDEF3JkLFgX0ab73CZ4GdJ9YaakJO7y4adFGzzIVLcn08UZ/pwDQ9BAuwuMc2yMnKihdvmLKbnAa1ATk9jFXQ9QAEMBHZLbPNvtS3pkpk0s6fyh2ceHa9Myy3fL/oqvPmq_14KzLgPZHaOlyb3tUoQM52fv/I78TqTGyB4WYD_vkm8gYHZcCF0dFIXsiXUbAbwR90Ldk8lsgxSL6rBvjPSlQq7N66NPzUVRYr3zSISupG_66uS4rJszHwmxmmraT3/zfVKxHXFHgxUDRmnwIMfdFKm4sf/qnRRccOLExJYGcZy8u65jo4gHDvO6vnpsdf0YtVWqDBJXa95/Y/qL7EYS73_t6/2xnWra9TTO0OtQNXEQ1XXLSLt6vPw1FTlE2aYCitDgUo7DyxiwuGtvmMKUkYCo/lqXouo2TGXZFF80lrCu1vKdxBgOOerlrsKrOJawGEzL8XzXdxkOMUT8HOzHPNOvDwsxc47mvpVzXEbX5DRaioOlm2U4flTG/6bZfLqJqHNtrKwC5U5NNG6_yNOW5Jg_bLmzUosi86IXxn7i04vRXXn92JmdE70TcdujehT1n15wtiD8ld5A65IV2W1801/wr0XcDIGiUSmxFfCozUCtBTFwln0uJ0cquSDXhj7JQADhYDGyz8WhqcPE7CP9xN93EUBrWczINbA4IsfckY8CZh68/Tak5dEhw8i_3rz/8U39D/iML1G_A8TsnKQ9/_S8o89fFc7Wx/f1nXF8H6OLVbPpp5IZg7UTZ2K0bSe3iBpsmkkJpxY_6zEHTJE3LbIANwF9Ik5Tu0ZJpjck7I07xlHR8mDW9FXclSQC/qJUGL5qByf2SY2Wd24hqKGrahLfqApQuRI8_DtU/Y8kH6DDif5kD6as3sIe6VbKYnU9c1URq/npTlE72m107FXxW9zktdzbBJAxt4udMFzjt2LPcBpqrMKGkrg4BHqKXwhFTspCWyYCjxJ/eFb3fd3BB5kb9D0yl3oOjeWtbJBqsboyzdLisRBn2MCtXO2O8eo4Hkm/2uJDoRjRCyIi2GNRkH0B3EkN6Z3vG40C985bAtM8eqHABzP2QRcKCz4ICOw_Xz249bJk8qM0/m4EeIWnx2ISf9TBU6_0KZ5QJ0VPOCPXxV9jCeK5W5/RV5nd7GUUXG0btDqUAa3DzpaRHX3klMAqL73hK4AGD3ItikmxF8vnSaqtsgOCpEePERt9qcUOJJP2aR0scPAf_1TkGSrgr5VF/XLM2i7YhC_3J9fA2Qwa0dbTedY/xGayjimEkuWSWvh7P5FNOum_l7qJPnA31lQq6ixqR0NKhO328rWfijqKHF6WR/5O0MJ4WNuIXk6xBtTOA9mK7CGUgWjaF5mB72PVnDpN8G6ERO39GqO/fCO96/A1mwIPWedF6HklU8jaQ_M5EUzwCsBE3/7FW2hbcD3GCOFCiLvObjn59o6CKoYlmTop/PZw2CLzvARAr5KaLhjIuZRSKTGlmYjvSoSELuvWi/QHUV7SJ0kF_1O3b_3a88cm/z7qD3Rp6MmoQdGPSyu1lXTpoETypgOMywfsr4ycV2LQr5XaE3UrQP/RzobA4rI_I3ceCUaRASmil2rV1TUiyljhdCFt8zmi1o2NyTzSBRNGP0lXU5Qtm6dKKp7lGRC19P2oSSFrxt85vWRNo1mv8odcL/TF7/MN1Ev7gY20MqlRSBrlwg5LZ4_Az7QnBnpbU3LkTC/oVb743VFtXMW4cK/3lw6wfBJZe_8DobxT_6/gCXp6QOs/LuqmrQHMQvTS6jfbqVFnPfLjrQ01Mb_F4lr3md6m87wpc1CYd9hdzgUL/aqz68HMDCxjGauC00Rajq9wGVYcWJ3j6rIaHIPwclftjARXFDg0yH8v/L6qDgIgGwbB3eZfjOXHAMXRFNMMihseZxYkcFAzLtYr94q9XpQeK4bKi9h_rWAMwcEHnS8/MHHlySbgy8azGEA0u9xsY96MRi45Qe74kZ9xlsI1t4Yutx8/gsjIiu7vNsKEyeTwd88BMExjWNcJHOSHRff57pJBMEAtPdbMETYorvUkRyErsqprxX0W45n0RRQ85w/JCOsYaxZOAFfzO0AdLpMCguFwl01fkFOKYrQeXfNn8w0KF4XS0k/fPx02fU7fFjUoXcPH7_9xo755WL8DNIU2ne4b6DpiROe473yUfD8_zSNUI1tpxzVYNA7GvVSYt8UtqHn3/_QwuOc4VeAI6RiAG5O5bcAxzQl96Q35emNwtTT_CYqHORCmyPj6By2hT_SCLf8m_xFxxe3YzvnxDZGq3qf__pq7Tw181/GosBAJy3MotiIxcYDASbY9sV4T2V/KoGHyJ64spdkQbJOHJ216JMSKj8ii5m8gxqJ2ypL81p5hbjWtjbUgSc8M_KTLuc0Owf1R/3vr/dKbQ2pJ4XEfXhnZTBQY7ZrClnVCnd5cMe9ic/aNF0yyOSQVVOecUFkK9IYFVR8VHdVf4/Nfu3nOEskHki1_r3At1HLOMniS6qNTvhS0hfqIuBiQBsd5aB7OdfVpYy1HdIR72gMToBlpHPsE5GrVO0J9/gcyB2xcyZ3UpTom8G3V48LUkk6kcJ6l1SL5Fgzbst0z3pDA4dzBfswbC8dW57_MkswDANNd8atPrOBSU5m2z66dP/mIYQ8iq/DcmBexkARDI47VzYuw5gwy8Lvym2_B2gxBokU9_T/fHCPjlpqjTsY6SgBOz1nlDh_HcSWYAqnyrZxbEO2erVJ4WPKNzjM3KaPXGH/dZryna1E28wxCrMqLCs9aL9oVBlDMjUcEryAyRh7xwN0uWGopdpkd7Du6O9EPjAj37sHkUiVs7WL6JyexoDF_n67MICvQnJ9FK/FVrp1uMZnmr7ijkMW87moNRBkXbVc2EA_hHOHmpbVGqr6WgNtJ7bBk1LrAPT8sKtE75vbe_L9VYqBHJ/njk.WIIj-V23pwC7ZahcIL0XnDPupL7ltwEc779Ofhrk9dt_wIOFsA8XwnCjrYqH2ty.F0XdS\"*;@kDYgfL4dwE/5I@>k|u0D:wGz\"_8=}RJM!Ybbwd}eN=ZB*esF&(iQ%FW]_FSA:3Ze4O*6&tG-Fe**/j^a&S8zIa#6gxL2NmnNMSVGF-Bf3z08tt0ug_UfNshhs4HJh0l1o24gjAN-Uck1OvWkGQSXH0glB7CnOm0gI", - "attempt_num": 8 - }, - { - "event_name": "dropped", - "processed": "2017-10-13T18:56:21Z", - "attempt_num": 3, - "url": "G_3c-1HtUkN4`puC&&!u>0OiStFG.ZoRi2=j%fUVa]&re6k{hKqD-8vWE12Fb5JC6z>S@@'cWS~w5KtuIwv$8/JDD94CXx1n5yjC_I2lQ66zDj4MXe/4bqlcqqQ7evnQWTYx5roaEYMapyuzb/USpsyalh/HcYc9PmQfF8ND_C7bXnwFQ_fb_BHMXbIV8JN28/NjZdawDJ6kSWxLykSVTHzcISGPBRfs_rt3Uc65Vzj6LDSSMN8WRs70m0tAWs/fkDvjvm_7ZeV08YZeB9j9mS9BcE089Fn5UzDlTJW9vqDF5uipjlIVrNbM7oWE/MIJcjg2vJO20jA24WHrchrEXCvKcxriviSDl3tuyDxqdqRSekpm2aH6yW7_ylXj/nWsex4jm3rKvYw1uLq3Tp7qb9edhj8B_TnwLv1yjHSkgbA5jKI4BTqxugmwVTnFf2OFCFp/ZILLkoKgfwOyIK4reUIkhCjuhkwp/cqGaFAkeCFQXPB6DLYesLZ2M3KPuBsBrs3pr3HRbTtwaOzdKtGc8e0C0VTjrJ3GwljStMPrSuQWh6/vigHRasZ4P9kFv5DPVbHWZzPvtwUw0AMByt44YH678WpbAXXy4I/IVOHmErZTbw1mJ/3vd4uI5rr2zEO_YA9qJZLJT/wmBimbOyaMtmTNYr_FhgfkKMN3_1la7RCK8CIP3p26mbuHbdJV1j/5sTIKibInM5l2BoWdEi49bPqzagsfjKpGVbg0YQ8mjrLhI92/qy0eVYi34kBGVuLzxK2FLC8vwYUrbupjUYE23Mc_6nmHYRK1HF1QmZDZG1hw96I3MPbTZqeJOWGch230qDNxOgnHRNNM52k/3c7FeuRr88RwZGpif/4FaSAbdqkUNvJ9J9qX2tJS9x5vZlgD8k4YHIXDztrnwg2VPquj/uo_2MjbWybIF/NGJM2RFAsKV1S5iOejuTV4p12KlH1p0Dt5EpxCSIl0XoWuvyLYar77f_hzqNdWAyL0FDxGfj4ma4jwqdTTLNyeZEtguYoCHTFfY/HgJkpHx/yO23G7gLhKPvD459ceffHidFh7LipTxNF0GFXhIAPrWfhv7PkPmVofBoFFlo6/rMcHQ82d5VS8i1CCyLtfuT5WH9GqrsOY7xo3lxi7BNL93/PLRdQT3SObRFRERw68V5ZFvIuEQqFOFZQ848rWPLXYDGY658dyjZALf/Ug4EROi_ehNtzPwecer_RGBHxeMnpxrPAFZEL6YXNKzm8hh3HY4Uc4fgkjge5fXsR4CeTSkS66/FOD00deDKmN7XcHEj1LGlAmd4XlV8vFpXg2VazX4OLW8z6vXn5vntNGYO6eBCEKUwupRz9nQSMeZ/Pbmjoopyt6TxQBUfPkHBdgCIhqA1zDV72ARqGlK_ao9KVjvgbB98YeiieIyogkuOa4y0E5iUEdBopzovVgtY88yLijh9ww/tl0R5rI2P2_OxguTbv_wrfEm8jRjISEIqSE9q29RB3n8PeD4hu24rcsaEuTMCqniiLN0a2OtZiKxHnbsNB660Aq3/tEo2SHZBkkIFYXBbDNE7gLfvFz9ZaC_E2oV2quyK1Id5SkNkJBVRRgROWBc_XEOXktc4vRUKxy1MQ526Xilyo8/uI67lHH1Vlr4V3GVmweT4A16KMqzmVzvRDRFLpkBv2iu3Okc1vIqkC/426aOqeUm6SXIx16d8BWVRcmqKqizxDEF3JkLFgX0ab73CZ4GdJ9YaakJO7y4adFGzzIVLcn08UZ/pwDQ9BAuwuMc2yMnKihdvmLKbnAa1ATk9jFXQ9QAEMBHZLbPNvtS3pkpk0s6fyh2ceHa9Myy3fL/oqvPmq_14KzLgPZHaOlyb3tUoQM52fv/I78TqTGyB4WYD_vkm8gYHZcCF0dFIXsiXUbAbwR90Ldk8lsgxSL6rBvjPSlQq7N66NPzUVRYr3zSISupG_66uS4rJszHwmxmmraT3/zfVKxHXFHgxUDRmnwIMfdFKm4sf/qnRRccOLExJYGcZy8u65jo4gHDvO6vnpsdf0YtVWqDBJXa95/Y/qL7EYS73_t6/2xnWra9TTO0OtQNXEQ1XXLSLt6vPw1FTlE2aYCitDgUo7DyxiwuGtvmMKUkYCo/lqXouo2TGXZFF80lrCu1vKdxBgOOerlrsKrOJawGEzL8XzXdxkOMUT8HOzHPNOvDwsxc47mvpVzXEbX5DRaioOlm2U4flTG/6bZfLqJqHNtrKwC5U5NNG6_yNOW5Jg_bLmzUosi86IXxn7i04vRXXn92JmdE70TcdujehT1n15wtiD8ld5A65IV2W1801/wr0XcDIGiUSmxFfCozUCtBTFwln0uJ0cquSDXhj7JQADhYDGyz8WhqcPE7CP9xN93EUBrWczINbA4IsfckY8CZh68/Tak5dEhw8i_3rz/8U39D/iML1G_A8TsnKQ9/_S8o89fFc7Wx/f1nXF8H6OLVbPpp5IZg7UTZ2K0bSe3iBpsmkkJpxY_6zEHTJE3LbIANwF9Ik5Tu0ZJpjck7I07xlHR8mDW9FXclSQC/qJUGL5qByf2SY2Wd24hqKGrahLfqApQuRI8_DtU/Y8kH6DDif5kD6as3sIe6VbKYnU9c1URq/npTlE72m107FXxW9zktdzbBJAxt4udMFzjt2LPcBpqrMKGkrg4BHqKXwhFTspCWyYCjxJ/eFb3fd3BB5kb9D0yl3oOjeWtbJBqsboyzdLisRBn2MCtXO2O8eo4Hkm/2uJDoRjRCyIi2GNRkH0B3EkN6Z3vG40C985bAtM8eqHABzP2QRcKCz4ICOw_Xz249bJk8qM0/m4EeIWnx2ISf9TBU6_0KZ5QJ0VPOCPXxV9jCeK5W5/RV5nd7GUUXG0btDqUAa3DzpaRHX3klMAqL73hK4AGD3ItikmxF8vnSaqtsgOCpEePERt9qcUOJJP2aR0scPAf_1TkGSrgr5VF/XLM2i7YhC_3J9fA2Qwa0dbTedY/xGayjimEkuWSWvh7P5FNOum_l7qJPnA31lQq6ixqR0NKhO328rWfijqKHF6WR/5O0MJ4WNuIXk6xBtTOA9mK7CGUgWjaF5mB72PVnDpN8G6ERO39GqO/fCO96/A1mwIPWedF6HklU8jaQ_M5EUzwCsBE3/7FW2hbcD3GCOFCiLvObjn59o6CKoYlmTop/PZw2CLzvARAr5KaLhjIuZRSKTGlmYjvSoSELuvWi/QHUV7SJ0kF_1O3b_3a88cm/z7qD3Rp6MmoQdGPSyu1lXTpoETypgOMywfsr4ycV2LQr5XaE3UrQP/RzobA4rI_I3ceCUaRASmil2rV1TUiyljhdCFt8zmi1o2NyTzSBRNGP0lXU5Qtm6dKKp7lGRC19P2oSSFrxt85vWRNo1mv8odcL/TF7/MN1Ev7gY20MqlRSBrlwg5LZ4_Az7QnBnpbU3LkTC/oVb743VFtXMW4cK/3lw6wfBJZe_8DobxT_6/gCXp6QOs/LuqmrQHMQvTS6jfbqVFnPfLjrQ01Mb_F4lr3md6m87wpc1CYd9hdzgUL/aqz68HMDCxjGauC00Rajq9wGVYcWJ3j6rIaHIPwclftjARXFDg0yH8v/L6qDgIgGwbB3eZfjOXHAMXRFNMMihseZxYkcFAzLtYr94q9XpQeK4bKi9h_rWAMwcEHnS8/MHHlySbgy8azGEA0u9xsY96MRi45Qe74kZ9xlsI1t4Yutx8/gsjIiu7vNsKEyeTwd88BMExjWNcJHOSHRff57pJBMEAtPdbMETYorvUkRyErsqprxX0W45n0RRQ85w/JCOsYaxZOAFfzO0AdLpMCguFwl01fkFOKYrQeXfNn8w0KF4XS0k/fPx02fU7fFjUoXcPH7_9xo755WL8DNIU2ne4b6DpiROe473yUfD8_zSNUI1tpxzVYNA7GvVSYt8UtqHn3/_QwuOc4VeAI6RiAG5O5bcAxzQl96Q35emNwtTT_CYqHORCmyPj6By2hT_SCLf8m_xFxxe3YzvnxDZGq3qf__pq7Tw181/GosBAJy3MotiIxcYDASbY9sV4T2V/KoGHyJ64spdkQbJOHJ216JMSKj8ii5m8gxqJ2ypL81p5hbjWtjbUgSc8M_KTLuc0Owf1R/3vr/dKbQ2pJ4XEfXhnZTBQY7ZrClnVCnd5cMe9ic/aNF0yyOSQVVOecUFkK9IYFVR8VHdVf4/Nfu3nOEskHki1_r3At1HLOMniS6qNTvhS0hfqIuBiQBsd5aB7OdfVpYy1HdIR72gMToBlpHPsE5GrVO0J9/gcyB2xcyZ3UpTom8G3V48LUkk6kcJ6l1SL5Fgzbst0z3pDA4dzBfswbC8dW57_MkswDANNd8atPrOBSU5m2z66dP/mIYQ8iq/DcmBexkARDI47VzYuw5gwy8Lvym2_B2gxBokU9_T/fHCPjlpqjTsY6SgBOz1nlDh_HcSWYAqnyrZxbEO2erVJ4WPKNzjM3KaPXGH/dZryna1E28wxCrMqLCs9aL9oVBlDMjUcEryAyRh7xwN0uWGopdpkd7Du6O9EPjAj37sHkUiVs7WL6JyexoDF_n67MICvQnJ9FK/FVrp1uMZnmr7ijkMW87moNRBkXbVc2EA_hHOHmpbVGqr6WgNtJ7bBk1LrAPT8sKtE75vbe_L9VYqBHJ/njk.WIIj-V23pwC7ZahcIL0XnDPupL7ltwEc779Ofhrk9dt_wIOFsA8XwnCjrYqH2ty.F0XdS\"*;@kDYgfL4dwE/5I@>k|u0D:wGz\"_8=}RJM!Ybbwd}eN=ZB*esF&(iQ%FW]_FSA:3Ze4O*6&tG-Fe**/j^a&S8zIa#6gxL2NmnNMSVGF-Bf3z08tt0ug_UfNshhs4HJh0l1o24gjAN-Uck1OvWkGQSXH0glB7CnOm0gI", - "bounce_type": "hard", - "mx_server": "laborum nisi", - "http_user_agent": "quis re" - } - ], - "originating_ip": "204.173.18.0", - "categories": ["dolor", "pie"], - "unique_args": "eu", - "outbound_ip": "181.40.184.87", - "outbound_ip_type": "dedicated", - "id": "2mMUdxV2HRfAeDiBTYs2IP" - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "invalid syntax: 'bad_field' is not a known field" - } - ] - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "not found", - "field": "message_id" - } - ] - } - } - } - } - } - }, - "429": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "too many requests" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET-v3-messages-msg_id", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - }, - "parameters": [ - { - "$ref": "#/components/parameters/trait_authorizationHeader_Authorization" - } - ] - } - }, - "/messages/download": { - "post": { - "operationId": "POST_v3-messages-download", - "summary": "Request CSV", - "tags": ["CSV (UI only)", "V3"], - "description": "This is BETA functionality. You may not have access, and we reserve the right to change functionality without notice.\n\nThis request will kick off a backend process to generate a CSV file. Once generated, the worker will then send an email for the user download the file. The link will expire in 3 days.\n\nThe CSV fill contain the last 1 million messages. This endpoint will be rate limited to 1 request every 12 hours (rate limit may change).\n\nThis endpoint is similar to the GET Single Message endpoint - the only difference is that /download is added to indicate that this is a CSV download requests but the same query is used to determine what the CSV should contain.", - "parameters": [ - { - "name": "query", - "in": "query", - "description": "Uses a SQL like syntax to indicate which messages to include in the CSV", - "required": false, - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_authorizationHeader_Authorization" - } - ], - "responses": { - "202": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "status": { - "type": "string", - "enum": ["pending"] - }, - "message": { - "type": "string" - } - } - }, - "examples": { - "response": { - "value": { - "status": "pending", - "message": "An email will be sent to jane_doe@example.com when the CSV is ready to download." - } - } - } - } - } - }, - "400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "some error" - } - ] - } - } - } - } - } - }, - "429": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "too many requests", - "field": "" - } - ] - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "internal server error" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_v3-messages-download", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/messages/download/{download_uuid}": { - "parameters": [ - { - "name": "download_uuid", - "in": "path", - "description": "UUID used to locate the download csv request entry in the DB.\n\nThis is the UUID provided in the email sent to the user when their csv file is ready to download", - "required": true, - "schema": { - "type": "string", - "format": "uuid" - } - } - ], - "get": { - "operationId": "GET_v3-messages-download-download_uuid", - "summary": "Download CSV", - "tags": ["CSV (UI only)", "V3"], - "description": "**This endpoint will return a presigned URL that can be used to download the CSV that was requested from the \"Request a CSV\" endpoint.**", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "presigned_url": { - "type": "string", - "format": "uri", - "description": "A signed link that will allow you to download the CSV file requested by the Request a CSV endpoint." - }, - "csv": { - "type": "string", - "minLength": 5, - "pattern": "^((http[s]?|ftp):\\/)?\\/?([^:\\/\\s]+)((\\/\\w+)*\\/)([\\w\\-\\.]+[^#?\\s]+)(.*)?(#[\\w\\-]+)?$", - "description": "Returns the aws signed link to the csv file which mako UI should perform a get on to trigger the csv download for the user" - } - }, - "required": ["csv"] - }, - "examples": { - "response": { - "value": { - "presigned_url": "https://example.com", - "csv": "https://s3-us-west-2.amazonaws.com/sendgrid-rts-development-queries/013c31af-7c9a-49e6-922c-d990f4aff151.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Credential=AKIAI4NOW7APZHRFYGWQ%2F20170728%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Date=20170728T223936Z&X-Amz-Signature=5c13ede58b211799ab1a556280bd316c404eac3aef1450c47906a077166c4ab4" - } - } - } - } - } - }, - "404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "download token is invalid or expired", - "field": "" - } - ] - } - } - } - } - } - }, - "500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "message": "internal server error" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_v3-messages-download-download_uuid", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - }, - "parameters": [ - { - "$ref": "#/components/parameters/trait_authorizationHeader_Authorization" - } - ] - } - }, - "/tracking_settings": { - "get": { - "operationId": "GET_tracking_settings", - "summary": "Retrieve Tracking Settings", - "tags": ["Settings - Tracking"], - "description": "**This endpoint allows you to retrieve a list of all tracking settings on your account.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "The list of all tracking settings.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the event being tracked." - }, - "title": { - "type": "string", - "description": "The title of the tracking setting." - }, - "description": { - "type": "string", - "description": "A description about the event that is being tracked." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this tracking setting is currently enabled." - } - } - } - } - } - }, - "examples": { - "response": { - "value": { - "result": [ - { - "name": "open", - "title": "Open Tracking", - "description": "lorem ipsum... .", - "enabled": true - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_trackingsettings", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/tracking_settings/click": { - "get": { - "operationId": "GET_tracking_settings-click", - "summary": "Retrieve Click Track Settings", - "tags": ["Settings - Tracking"], - "description": "**This endpoint allows you to retrieve your current click tracking setting.**\n\nClick Tracking overrides all the links and URLs in your emails and points them to either SendGrid’s servers or the domain with which you branded your link. When a customer clicks a link, SendGrid tracks those [clicks](https://sendgrid.com/docs/glossary/clicks/).\n\nClick tracking helps you understand how users are engaging with your communications. SendGrid can track up to 1000 links per email", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/click-tracking" - }, - "examples": { - "response": { - "value": { - "enable_text": false, - "enabled": true - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_trackingsettings-click", - "public": true, - "mock": { - "dynamic": false, - "statusCode": 200, - "enabled": false - } - } - }, - "patch": { - "operationId": "PATCH_tracking_settings-click", - "summary": "Update Click Tracking Settings", - "tags": ["Settings - Tracking"], - "description": "**This endpoint allows you to enable or disable your current click tracking setting.**\n\nClick Tracking overrides all the links and URLs in your emails and points them to either SendGrid’s servers or the domain with which you branded your link. When a customer clicks a link, SendGrid tracks those [clicks](https://sendgrid.com/docs/glossary/clicks/).\n\nClick tracking helps you understand how users are engaging with your communications. SendGrid can track up to 1000 links per email", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "The setting you want to use for click tracking." - } - }, - "example": { - "enabled": true - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/click-tracking" - }, - "examples": { - "response": { - "value": { - "enable_text": false, - "enabled": true - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_trackingsettings-click", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/tracking_settings/google_analytics": { - "get": { - "operationId": "GET_tracking_settings-google_analytics", - "summary": "Retrieve Google Analytics Settings", - "tags": ["Settings - Tracking"], - "description": "**This endpoint allows you to retrieve your current setting for Google Analytics.**\n\n\nGoogle Analytics helps you understand how users got to your site and what they're doing there. For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on [\"Best Practices for Campaign Building\"](https://support.google.com/analytics/answer/1037445).\n\nWe default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/ui/analytics-and-reporting/google-analytics/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/google_analytics_settings" - }, - "examples": { - "response": { - "value": { - "enabled": true, - "utm_campaign": "", - "utm_content": "lotsandlotsofcontent", - "utm_medium": "", - "utm_source": "", - "utm_term": "" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_trackingsettings-googleanalytics", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_tracking_settings-google_analytics", - "summary": "Update Google Analytics Settings", - "tags": ["Settings - Tracking"], - "description": "**This endpoint allows you to update your current setting for Google Analytics.**\n\nGoogle Analytics helps you understand how users got to your site and what they're doing there. For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on [\"Best Practices for Campaign Building\"](https://support.google.com/analytics/answer/1037445).\n\nWe default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/ui/analytics-and-reporting/google-analytics/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/google_analytics_settings" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/google_analytics_settings" - }, - "examples": { - "response": { - "value": { - "enabled": true, - "utm_campaign": "", - "utm_content": "lotsandlotsofcontent", - "utm_medium": "", - "utm_source": "", - "utm_term": "" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_trackingsettings-googleanalytics", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/tracking_settings/open": { - "get": { - "operationId": "GET_tracking_settings-open", - "summary": "Get Open Tracking Settings", - "tags": ["Settings - Tracking"], - "description": "**This endpoint allows you to retrieve your current settings for open tracking.**\n\nOpen Tracking adds an invisible image at the end of the email which can track email opens.\n\nIf the email recipient has images enabled on their email client, a request to SendGrid’s server for the invisible image is executed and an open event is logged.\n\nThese events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if open tracking is enabled." - } - }, - "required": ["enabled"] - }, - "examples": { - "response": { - "value": { - "enabled": true - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_trackingsettings-open", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_tracking_settings-open", - "summary": "Update Open Tracking Settings", - "tags": ["Settings - Tracking"], - "description": "**This endpoint allows you to update your current settings for open tracking.**\n\nOpen Tracking adds an invisible image at the end of the email which can track email opens.\n\nIf the email recipient has images enabled on their email client, a request to SendGrid’s server for the invisible image is executed and an open event is logged.\n\nThese events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "The new status that you want to set for open tracking." - } - }, - "example": { - "enabled": true - } - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if open tracking is enabled." - } - }, - "required": ["enabled"] - }, - "examples": { - "response": { - "value": { - "enabled": true - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_trackingsettings-open", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/tracking_settings/subscription": { - "get": { - "operationId": "GET_tracking_settings-subscription", - "summary": "Retrieve Subscription Tracking Settings", - "tags": ["Settings - Tracking"], - "description": "**This endpoint allows you to retrieve your current settings for subscription tracking.**\n\nSubscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/subscription_tracking_settings" - }, - "examples": { - "response": { - "value": { - "enabled": true, - "html_content": "

Something something unsubscribe <% %> something something

\n", - "landing": "

subscribehere

\n", - "plain_content": "Something something unsubscribe <% %> something something", - "replace": "thetag", - "url": "http://mydomain.com/parse" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_trackingsettings-subscription", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_tracking_settings-subscription", - "summary": "Update Subscription Tracking Settings", - "tags": ["Settings - Tracking"], - "description": "**This endpoint allows you to update your current settings for subscription tracking.**\n\nSubscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/subscription_tracking_settings" - } - } - } - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/subscription_tracking_settings" - }, - "examples": { - "response": { - "value": { - "enabled": true, - "landing": "landing page html", - "url": "http://mydomain.com/parse", - "replace": "replacement tag", - "html_content": "html content", - "plain_content": "text content" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_trackingsettings-subscription", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/stats": { - "get": { - "operationId": "GET_stats", - "summary": "Retrieve global email statistics", - "tags": ["Stats"], - "description": "**This endpoint allows you to retrieve all of your global email statistics between a given date range.**\n\nParent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_limit" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_offset" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_aggregated_by" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_start_date" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_end_date" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date the stats were gathered." - }, - "stats": { - "type": "array", - "description": "The individual email activity stats.", - "items": { - "type": "object", - "properties": { - "metrics": { - "$ref": "#/components/schemas/stats-advanced-global-stats" - } - } - } - } - }, - "required": ["date", "stats"] - } - }, - "examples": { - "response": { - "value": [ - { - "date": "2015-11-03", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_stats", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/geo/stats": { - "get": { - "operationId": "GET_geo-stats", - "summary": "Retrieve email statistics by country and state/province.", - "tags": ["Stats"], - "description": "**This endpoint allows you to retrieve your email statistics segmented by country and state/province.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", - "parameters": [ - { - "name": "country", - "in": "query", - "description": "The country you would like to see statistics for. Currently only supported for US and CA.", - "schema": { - "type": "string", - "enum": ["US", "CA"] - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_limit" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_offset" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_aggregated_by" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_start_date" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_end_date" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the statistics were gathered." - }, - "stats": { - "type": "array", - "description": "The list of statistics.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "$ref": "#/components/schemas/advanced_stats_clicks_opens" - } - } - } - } - } - } - }, - "examples": { - "response": { - "value": [ - { - "date": "2015-10-11", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-17", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 1, - "unique_clicks": 0, - "unique_opens": 1 - } - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-25", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-26", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-28", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-29", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-30", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-31", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-02", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-03", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-10", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_geo-stats", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/devices/stats": { - "get": { - "operationId": "GET_devices-stats", - "summary": "Retrieve email statistics by device type.", - "tags": ["Stats"], - "description": "**This endpoint allows you to retrieve your email statistics segmented by the device type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Device Types\n| **Device** | **Description** | **Example** |\n|---|---|---|\n| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |\n| Webmail |\tA web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. |\n| Phone | A smart phone. | iPhone, Android, Blackberry, etc.\n| Tablet | A tablet computer. | iPad, android based tablet, etc. |\n| Other | An unrecognized device. |\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_limit" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_offset" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_aggregated_by" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_start_date" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_end_date" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the statistics were gathered." - }, - "stats": { - "type": "array", - "description": "The list of statistics.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "$ref": "#/components/schemas/advanced_stats_opens" - } - } - } - } - } - } - }, - "examples": { - "response": { - "value": [ - { - "date": "2015-10-11", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-17", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 1, - "unique_opens": 1 - } - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-25", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-26", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 2, - "unique_opens": 2 - } - } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-28", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-29", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-30", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-31", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-02", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-03", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-10", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_devices-stats", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/clients/stats": { - "get": { - "operationId": "GET_clients-stats", - "summary": "Retrieve email statistics by client type.", - "tags": ["Stats"], - "description": "**This endpoint allows you to retrieve your email statistics segmented by client type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedStatsBaseQueryStrings_start_date" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedStatsBaseQueryStrings_end_date" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedStatsBaseQueryStrings_aggregated_by" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the statistics were gathered." - }, - "stats": { - "type": "array", - "description": "The list of statistics.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "$ref": "#/components/schemas/advanced_stats_opens" - } - } - } - } - } - } - }, - "examples": { - "response": { - "value": [ - { - "date": "2014-10-01", - "stats": [ - { - "metrics": { - "opens": 1, - "unique_opens": 1 - }, - "name": "Gmail", - "type": "client" - } - ] - }, - { - "date": "2014-10-02", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "client" - } - ] - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_clients-stats", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/clients/{client_type}/stats": { - "parameters": [ - { - "name": "client_type", - "in": "path", - "description": "Specifies the type of client to retrieve stats for. Must be either \"phone\", \"tablet\", \"webmail\", or \"desktop\".", - "required": true, - "schema": { - "type": "string", - "enum": ["phone", "tablet", "webmail", "desktop"] - } - } - ], - "get": { - "operationId": "GET_clients-client_type-stats", - "summary": "Retrieve stats by a specific client type.", - "tags": ["Stats"], - "description": "**This endpoint allows you to retrieve your email statistics segmented by a specific client type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Client Types\n- phone\n- tablet\n- webmail\n- desktop\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedStatsBaseQueryStrings_start_date" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedStatsBaseQueryStrings_end_date" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedStatsBaseQueryStrings_aggregated_by" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the statistics were gathered." - }, - "stats": { - "type": "array", - "description": "The list of statistics.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "$ref": "#/components/schemas/advanced_stats_opens" - } - } - } - } - } - } - }, - "examples": { - "response": { - "value": [ - { - "date": "2014-10-01", - "stats": [ - { - "metrics": { - "opens": 1, - "unique_opens": 1 - }, - "name": "Gmail", - "type": "client" - } - ] - }, - { - "date": "2014-10-02", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "client" - } - ] - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_clients-clienttype-stats", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/mailbox_providers/stats": { - "get": { - "operationId": "GET_mailbox_providers-stats", - "summary": "Retrieve email statistics by mailbox provider.", - "tags": ["Stats"], - "description": "**This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", - "parameters": [ - { - "name": "mailbox_providers", - "in": "query", - "description": "The mail box providers to get statistics for. You can include up to 10 by including this parameter multiple times.", - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_limit" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_offset" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_aggregated_by" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_start_date" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_end_date" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the statistics were gathered." - }, - "stats": { - "type": "array", - "description": "The list of statistics.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "$ref": "#/components/schemas/advanced_stats_mailbox_provider" - } - } - } - } - } - } - }, - "examples": { - "response": { - "value": [ - { - "date": "2015-10-11", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-17", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 1, - "drops": 0, - "opens": 1, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 1 - } - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-25", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-26", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 2, - "drops": 0, - "opens": 2, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 2 - } - } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-28", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-29", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-30", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-31", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-02", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-03", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-10", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_mailboxproviders-stats", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/browsers/stats": { - "get": { - "operationId": "GET_browsers-stats", - "summary": "Retrieve email statistics by browser.", - "tags": ["Stats"], - "description": "**This endpoint allows you to retrieve your email statistics segmented by browser type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", - "parameters": [ - { - "name": "browsers", - "in": "query", - "description": "The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times.", - "schema": { - "type": "string" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_limit" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_offset" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_aggregated_by" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_start_date" - }, - { - "$ref": "#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_end_date" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the statistics were gathered." - }, - "stats": { - "type": "array", - "description": "The list of statistics.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "$ref": "#/components/schemas/advanced_stats_clicks" - } - } - } - } - } - } - }, - "examples": { - "response": { - "value": [ - { - "date": "2014-10-01", - "stats": [ - { - "metrics": { - "clicks": 0, - "unique_clicks": 0 - }, - "name": "Chrome", - "type": "browser" - }, - { - "metrics": { - "clicks": 1, - "unique_clicks": 1 - }, - "name": "Firefox", - "type": "browser" - } - ] - }, - { - "date": "2014-10-02", - "stats": [ - { - "metrics": { - "clicks": 0, - "unique_clicks": 0 - }, - "name": "Chrome", - "type": "browser" - }, - { - "metrics": { - "clicks": 1, - "unique_clicks": 1 - }, - "name": "Firefox", - "type": "browser" - } - ] - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_browsers-stats", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/suppression/bounces": { - "get": { - "operationId": "GET_suppression-bounces", - "summary": "Retrieve all bounces", - "tags": ["Bounces API"], - "description": "**This endpoint allows you to retrieve all of your bounces.**", - "parameters": [ - { - "name": "start_time", - "in": "query", - "description": "Refers start of the time range in unix timestamp when a bounce was created (inclusive).", - "schema": { - "type": "integer" - } - }, - { - "name": "end_time", - "in": "query", - "description": "Refers end of the time range in unix timestamp when a bounce was created (inclusive).", - "schema": { - "type": "integer" - } - }, - { - "name": "Accept", - "in": "header", - "required": true, - "schema": { - "type": "string", - "default": "application/json" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/bounce_response" - } - }, - "examples": { - "response": { - "value": [ - { - "created": 1250337600, - "email": "example@example.com", - "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ", - "status": "5.1.1" - }, - { - "created": 1250337600, - "email": "example@example.com", - "reason": "550 5.1.1 : Recipient address rejected: User unknown in virtual alias table ", - "status": "5.1.1" - } - ] - } - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_suppression-bounces", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_suppression-bounces", - "summary": "Delete bounces", - "tags": ["Bounces API"], - "description": "**This endpoint allows you to delete all emails on your bounces list.**\n\nThere are two options for deleting bounced emails: \n\n1. You can delete all bounced emails by setting `delete_all` to `true` in the request body. \n2. You can delete a selection of bounced emails by specifying the email addresses in the `emails` array of the request body.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "delete_all": { - "type": "boolean", - "description": "This parameter allows you to delete **every** email in your bounce list. This should not be used with the emails parameter." - }, - "emails": { - "type": "array", - "description": "Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter.", - "items": { - "type": "string" - } - } - }, - "example": { - "delete_all": false, - "emails": ["example@example.com", "example2@example.com"] - } - } - } - } - }, - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "nullable": true - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_suppression-bounces", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/suppression/bounces/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_suppression-bounces-email", - "summary": "Retrieve a Bounce", - "tags": ["Bounces API"], - "description": "**This endpoint allows you to retrieve a specific bounce by email address.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/bounce_response" - } - }, - "examples": { - "response": { - "value": [ - { - "created": 1443651125, - "email": "bounce1@test.com", - "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ", - "status": "5.1.1" - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_suppression-bounces-email", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_suppression-bounces-email", - "summary": "Delete a bounce", - "tags": ["Bounces API"], - "description": "**This endpoint allows you to remove an email address from your bounce list.**", - "parameters": [ - { - "name": "email_address", - "in": "query", - "description": "The email address you would like to remove from the bounce list.", - "required": true, - "schema": { - "type": "string", - "format": "email" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/DELETE_contactdb-lists-list_idBody" - }, - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - }, - "examples": { - "response": { - "value": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_suppression-bounces-email", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/suppression/blocks": { - "get": { - "operationId": "GET_suppression-blocks", - "summary": "Retrieve all blocks", - "tags": ["Blocks API"], - "description": "**This endpoint allows you to retrieve all email addresses that are currently on your blocks list.**", - "parameters": [ - { - "name": "start_time", - "in": "query", - "description": "The start of the time range when a blocked email was created (inclusive). This is a unix timestamp.", - "schema": { - "type": "integer" - } - }, - { - "name": "end_time", - "in": "query", - "description": "The end of the time range when a blocked email was created (inclusive). This is a unix timestamp.", - "schema": { - "type": "integer" - } - }, - { - "name": "limit", - "in": "query", - "description": "Limit the number of results to be displayed per page.", - "schema": { - "type": "integer" - } - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list to begin displaying results.", - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/blocks-response" - }, - "examples": { - "response": { - "value": [ - { - "created": 1443651154, - "email": "example@example.com", - "reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host", - "status": "4.0.0" - }, - { - "created": 1443651155, - "email": "example1@example.com", - "reason": "unable to resolve MX record for example.com: servfail", - "status": "4.0.0" - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_suppression-blocks", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_suppression-blocks", - "summary": "Delete blocks", - "tags": ["Blocks API"], - "description": "**This endpoint allows you to delete all email addresses on your blocks list.**\n\nThere are two options for deleting blocked emails: \n\n1. You can delete all blocked emails by setting `delete_all` to `true` in the request body. \n2. You can delete a selection of blocked emails by specifying the email addresses in the `emails` array of the request body.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "delete_all": { - "type": "boolean", - "description": "Indicates if you want to delete all blocked email addresses." - }, - "emails": { - "type": "array", - "description": "The specific blocked email addresses that you want to delete.", - "items": { - "type": "string" - } - } - }, - "example": { - "delete_all": false, - "emails": ["example1@example.com", "example2@example.com"] - } - } - } - } - }, - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_suppression-blocks", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 200 - } - } - } - }, - "/suppression/blocks/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "description": "The email address of the specific block.", - "required": true, - "schema": { - "type": "string", - "format": "email" - } - } - ], - "get": { - "operationId": "GET_suppression-blocks-email", - "summary": "Retrieve a specific block", - "tags": ["Blocks API"], - "description": "**This endpoint allows you to retrieve a specific email address from your blocks list.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/blocks-response" - }, - "examples": { - "response": { - "value": [ - { - "created": 1443651154, - "email": "example@example.com", - "reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host", - "status": "4.0.0" - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_suppression-blocks-email", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_suppression-blocks-email", - "summary": "Delete a specific block", - "tags": ["Blocks API"], - "description": "**This endpoint allows you to delete a specific email address from your blocks list.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_suppression-blocks-email", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/suppression/spam_reports": { - "get": { - "operationId": "GET_suppression-spam_reports", - "summary": "Retrieve all spam reports", - "tags": ["Spam Reports API"], - "description": "**This endpoint allows you to retrieve all spam reports.**", - "parameters": [ - { - "name": "start_time", - "in": "query", - "description": "The start of the time range when a spam report was created (inclusive). This is a unix timestamp.", - "schema": { - "type": "integer" - } - }, - { - "name": "end_time", - "in": "query", - "description": "The end of the time range when a spam report was created (inclusive). This is a unix timestamp.", - "schema": { - "type": "integer" - } - }, - { - "name": "limit", - "in": "query", - "description": "Limit the number of results to be displayed per page.", - "schema": { - "type": "integer" - } - }, - { - "name": "offset", - "in": "query", - "description": "Paging offset. The point in the list to begin displaying results.", - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/spam-reports-response" - }, - "examples": { - "response": { - "value": [ - { - "created": 1443651141, - "email": "user1@example.com", - "ip": "10.63.202.100" - }, - { - "created": 1443651154, - "email": "user2@example.com", - "ip": "10.63.202.100" - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_suppression-spamreports", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_suppression-spam_reports", - "summary": "Delete spam reports", - "tags": ["Spam Reports API"], - "description": "**This endpoint allows you to delete your spam reports.**\n\nDeleting a spam report will remove the suppression, meaning email will once again be sent to the previously suppressed address. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.\n\nThere are two options for deleting spam reports: \n\n1. You can delete all spam reports by setting the `delete_all` field to `true` in the request body.\n2. You can delete a list of select spam reports by specifying the email addresses in the `emails` array of the request body.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "delete_all": { - "type": "boolean", - "description": "Indicates if you want to delete all email addresses on the spam report list." - }, - "emails": { - "type": "array", - "description": "A list of specific email addresses that you want to remove from the spam report list.", - "items": { - "type": "string" - } - } - }, - "example": { - "delete_all": false, - "emails": ["example1@example.com", "example2@example.com"] - } - } - } - } - }, - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_suppression-spamreports", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 200 - } - } - } - }, - "/suppression/spam_reports/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "description": "The email address of a specific spam report that you want to retrieve.", - "required": true, - "schema": { - "type": "string", - "format": "email" - } - } - ], - "get": { - "operationId": "GET_suppression-spam_reports-email", - "summary": "Retrieve a specific spam report", - "tags": ["Spam Reports API"], - "description": "**This endpoint allows you to retrieve a specific spam report by email address.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/spam-reports-response" - }, - "examples": { - "response": { - "value": [ - { - "created": 1454433146, - "email": "test1@example.com", - "ip": "10.89.32.5" - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_suppression-spamreports-email", - "public": true, - "mock": { - "statusCode": 200, - "dynamic": false, - "enabled": false - } - } - }, - "delete": { - "operationId": "DELETE_suppression-spam_reports-email", - "summary": "Delete a specific spam report", - "tags": ["Spam Reports API"], - "description": "**This endpoint allows you to delete a specific spam report by email address.**\n\nDeleting a spam report will remove the suppression, meaning email will once again be sent to the previously suppressed address. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_suppression-spamreports-email", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/asm/suppressions/global": { - "post": { - "operationId": "POST_asm-suppressions-global", - "summary": "Add recipient addresses to the global suppression group.", - "tags": ["Suppressions - Global Suppressions"], - "description": "**This endpoint allows you to add one or more email addresses to the global suppressions group.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/suppressions-request" - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "description": "The email addresses that are globally suppressed", - "items": { - "type": "string", - "format": "email" - } - } - }, - "required": ["recipient_emails"] - }, - "examples": { - "response": { - "value": { - "recipient_emails": ["test1@example.com", "test2@example.com"] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_asm-suppressions-global", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/suppression/unsubscribes": { - "get": { - "operationId": "GET_suppression-unsubscribes", - "summary": "Retrieve all global suppressions", - "tags": ["Suppressions - Global Suppressions"], - "description": "**This endpoint allows you to retrieve a list of all email address that are globally suppressed.**", - "parameters": [ - { - "name": "start_time", - "in": "query", - "description": "Refers start of the time range in unix timestamp when an unsubscribe email was created (inclusive).", - "schema": { - "type": "integer" - } - }, - { - "name": "end_time", - "in": "query", - "description": "Refers end of the time range in unix timestamp when an unsubscribe email was created (inclusive).", - "schema": { - "type": "integer" - } - }, - { - "name": "limit", - "in": "query", - "description": "The number of results to display on each page.", - "schema": { - "type": "integer" - } - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list of results to begin displaying global suppressions.", - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer", - "description": "A Unix timestamp indicating when the recipient was added to the global suppression list." - }, - "email": { - "type": "string", - "description": "The email address of the recipient who is globally suppressed.", - "format": "email" - } - }, - "required": ["created", "email"] - } - }, - "examples": { - "response": { - "value": [ - { - "created": 1443651141, - "email": "user1@example.com" - }, - { - "created": 1443651154, - "email": "user2@example.com" - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_suppression-unsubscribes", - "public": true, - "mock": { - "dynamic": false, - "enabled": false, - "statusCode": 200 - } - } - } - }, - "/asm/suppressions/global/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "description": "The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_asm-suppressions-global-email", - "summary": "Retrieve a Global Suppression", - "tags": ["Suppressions - Global Suppressions"], - "description": "**This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.**\n\nIf the email address you include in the URL path parameter `{email}` is already globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "title": "Retrieve a Global Suppression response", - "type": "object", - "properties": { - "recipient_email": { - "type": "string", - "description": "The email address that is globally suppressed. This will be an empty object if the email address you included in your call is not globally suppressed.", - "format": "email" - } - }, - "required": ["recipient_email"] - }, - "examples": { - "response": { - "value": { - "recipient_email": "test@example.com" - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_asm-suppressions-global-email", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_asm-suppressions-global-email", - "summary": "Delete a Global Suppression", - "tags": ["Suppressions - Global Suppressions"], - "description": "**This endpoint allows you to remove an email address from the global suppressions group.**\n\nDeleting a suppression group will remove the suppression, meaning email will once again be sent to the previously suppressed addresses. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_asm-suppressions-global-email", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/asm/groups": { - "post": { - "operationId": "POST_asm-groups", - "summary": "Create a new suppression group", - "tags": ["Suppressions - Unsubscribe Groups"], - "description": "**This endpoint allows you to create a new suppression group.**\n\nTo add an email address to the suppression group, [create a Suppression](https://sendgrid.api-docs.io/v3.0/suppressions-suppressions/add-suppressions-to-a-suppression-group).", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/suppression-group-request-base" - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the suppression group." - }, - "name": { - "type": "string", - "description": "The name of the suppression group." - }, - "description": { - "type": "string", - "description": "A brief description of the suppression group." - }, - "is_default": { - "type": "boolean", - "description": "Indicates if this is the default suppression group." - } - }, - "required": ["id", "name", "description", "is_default"] - }, - "examples": { - "response": { - "value": { - "id": 103, - "name": "Product Suggestions", - "description": "Suggestions for products our users might like.", - "is_default": false - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_asm-groups", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "get": { - "operationId": "GET_asm-groups", - "summary": "Retrieve all suppression groups associated with the user.", - "tags": ["Suppressions - Unsubscribe Groups"], - "description": "**This endpoint allows you to retrieve a list of all suppression groups created by this user.**\n\nThis endpoint can also return information for multiple group IDs that you include in your request. To add a group ID to your request, simply append `?id=123456&id=123456`, with the appropriate group IDs.", - "parameters": [ - { - "name": "id", - "in": "query", - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/suppression_group" - } - }, - "examples": { - "response": { - "value": [ - { - "id": 1234, - "name": "Unsubscribe Group", - "description": "An Unsubscribe Group", - "last_email_sent_at": null, - "is_default": true, - "unsubscribes": 1234 - }, - { - "id": 1234, - "name": "Unsubscribe Group", - "description": "An Unsubscribe Group", - "last_email_sent_at": null, - "is_default": true, - "unsubscribes": 1234 - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_asm-groups", - "public": true, - "mock": { - "statusCode": 200, - "enabled": false, - "dynamic": false - } - } - } - }, - "/asm/groups/{group_id}": { - "parameters": [ - { - "name": "group_id", - "in": "path", - "description": "The ID of the suppression group you would like to retrieve.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_asm-groups-group_id", - "summary": "Get information on a single suppression group.", - "tags": ["Suppressions - Unsubscribe Groups"], - "description": "**This endpoint allows you to retrieve a single suppression group.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/suppression-group-request-base" - }, - { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the suppression group." - }, - "unsubscribes": { - "type": "integer", - "description": "The number of unsubscribes, or suppressions, in this group." - }, - "last_email_sent_at": { - "nullable": true, - "type": "string" - } - }, - "required": ["id"] - } - ] - }, - "examples": { - "response": { - "value": { - "description": "Our monthly newsletter.", - "id": 100, - "is_default": true, - "last_email_sent_at": null, - "name": "Newsletters", - "unsubscribes": 400 - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_asm-groups-groupid", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "patch": { - "operationId": "PATCH_asm-groups-group_id", - "summary": "Update a suppression group.", - "tags": ["Suppressions - Unsubscribe Groups"], - "description": "**This endpoint allows you to update or change a suppression group.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/suppression-group-request-base" - } - ], - "example": { - "id": 103, - "name": "Item Suggestions", - "description": "Suggestions for items our users might like." - } - } - } - } - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/suppression_group" - }, - "examples": { - "response": { - "value": { - "id": 103, - "name": "Item Suggestions", - "description": "Suggestions for items our users might like." - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_asm-groups-groupid", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_asm-groups-group_id", - "summary": "Delete a Suppression Group", - "tags": ["Suppressions - Unsubscribe Groups"], - "description": "**This endpoint allows you to delete a suppression group.**\n\nIf a recipient uses the \"one-click unsubscribe\" option on an email associated with a deleted group, that recipient will be added to the global suppression list.\n\nDeleting a suppression group will remove the suppression, meaning email will once again be sent to the previously suppressed addresses. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_asm-groups-groupid", - "public": true, - "mock": { - "statusCode": 204, - "dynamic": false - } - } - } - }, - "/asm/groups/{group_id}/suppressions": { - "parameters": [ - { - "name": "group_id", - "in": "path", - "description": "The id of the unsubscribe group that you are adding suppressions to.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "post": { - "operationId": "POST_asm-groups-group_id-suppressions", - "summary": "Add suppressions to a suppression group", - "tags": ["Suppressions - Suppressions"], - "description": "**This endpoint allows you to add email addresses to an unsubscribe group.**\n\nIf you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/suppressions-request" - }, - "responses": { - "201": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "description": "The email addresses you added to the unsubscribe group", - "items": { - "type": "string", - "format": "email" - } - } - } - }, - "examples": { - "response": { - "value": { - "recipient_emails": ["test1@example.com", "test2@example.com"] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_asm-groups-groupid-suppressions", - "public": true, - "mock": { - "dynamic": false - } - } - }, - "get": { - "operationId": "GET_asm-groups-group_id-suppressions", - "summary": "Retrieve all suppressions for a suppression group", - "tags": ["Suppressions - Suppressions"], - "description": "**This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "description": "The list of email addresses belonging to the given suppression group.", - "items": { - "type": "string", - "format": "email" - } - }, - "examples": { - "response": { - "value": ["example@example.com", "example2@example.com"] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_asm-groups-groupid-suppressions", - "public": true, - "mock": { - "dynamic": false - } - } - } - }, - "/asm/groups/{group_id}/suppressions/search": { - "parameters": [ - { - "name": "group_id", - "in": "path", - "description": "The ID of the suppression group that you would like to search.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "post": { - "operationId": "POST_asm-groups-group_id-suppressions-search", - "summary": "Search for suppressions within a group", - "tags": ["Suppressions - Suppressions"], - "description": "**This endpoint allows you to search a suppression group for multiple suppressions.**\n\nWhen given a list of email addresses and a group ID, this endpoint will only return the email addresses that have been unsubscribed from the given group.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/suppressions-request" - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "description": "The email address from your search that do exist in the suppression group.", - "items": { - "type": "string", - "format": "email" - } - }, - "examples": { - "response": { - "value": ["exists1@example.com", "exists2@example.com"] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "POST_asm-groups-groupid-suppressions-search", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/asm/suppressions": { - "get": { - "operationId": "GET_asm-suppressions", - "summary": "Retrieve all suppressions", - "tags": ["Suppressions - Suppressions"], - "description": "**This endpoint allows you to retrieve a list of all suppressions.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address that was suppressed." - }, - "group_id": { - "type": "integer", - "description": "The id of the suppression group that this email address belongs to." - }, - "group_name": { - "type": "string", - "description": "The name of the suppression group that this email address belongs to." - }, - "created_at": { - "type": "integer", - "description": "A UNIX timestamp indicating when the suppression was created." - } - }, - "required": ["email", "group_id", "group_name", "created_at"] - } - }, - "examples": { - "response": { - "value": [ - { - "email": "test1@example.com", - "group_id": 1, - "group_name": "Weekly News", - "created_at": 1410986704 - }, - { - "email": "test1@example.com", - "group_id": 2, - "group_name": "Daily News", - "created_at": 1411493671 - }, - { - "email": "test2@example.com", - "group_id": 2, - "group_name": "Daily News", - "created_at": 1411493671 - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_asm-suppressions", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/asm/suppressions/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "description": "The email address that you want to search suppression groups for.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_asm-suppressions-email", - "summary": "Retrieve all suppression groups for an email address", - "tags": ["Suppressions - Suppressions"], - "description": "**This endpoint returns a list of all groups from which the given email address has been unsubscribed.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "suppressions": { - "type": "array", - "description": "The array of suppression groups.", - "items": { - "type": "object", - "properties": { - "description": { - "type": "string", - "description": "The description of the suppression group." - }, - "id": { - "type": "integer", - "description": "The id of the suppression group." - }, - "is_default": { - "type": "boolean", - "description": "Indicates if the suppression group is set as the default." - }, - "name": { - "type": "string", - "description": "The name of the suppression group." - }, - "suppressed": { - "type": "boolean", - "description": "Indicates if the given email address is suppressed for this group." - } - }, - "required": ["description", "id", "is_default", "name", "suppressed"] - } - } - }, - "required": ["suppressions"] - }, - "examples": { - "response": { - "value": { - "suppressions": [ - { - "description": "Optional description.", - "id": 1, - "is_default": true, - "name": "Weekly News", - "suppressed": true - }, - { - "description": "Some daily news.", - "id": 2, - "is_default": true, - "name": "Daily News", - "suppressed": true - }, - { - "description": "An old group.", - "id": 2, - "is_default": false, - "name": "Old News", - "suppressed": false - } - ] - } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_asm-suppressions-email", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - }, - "/asm/groups/{group_id}/suppressions/{email}": { - "parameters": [ - { - "name": "group_id", - "in": "path", - "description": "The id of the suppression group that you are removing an email address from.", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "email", - "in": "path", - "description": "The email address that you want to remove from the suppression group.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "delete": { - "operationId": "DELETE_asm-groups-group_id-suppressions-email", - "summary": "Delete a suppression from a suppression group", - "tags": ["Suppressions - Suppressions"], - "description": "**This endpoint allows you to remove a suppressed email address from the given suppression group.**\n\nRemoving an address will remove the suppression, meaning email will once again be sent to the previously suppressed addresses. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "nullable": true - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_asm-groups-groupid-suppressions-email", - "public": true, - "mock": { - "statusCode": 204, - "dynamic": false - } - } - } - }, - "/suppression/invalid_emails": { - "get": { - "operationId": "GET_suppression-invalid_emails", - "summary": "Retrieve all invalid emails", - "tags": ["Invalid Emails API"], - "description": "**This endpoint allows you to retrieve a list of all invalid email addresses.**", - "parameters": [ - { - "name": "start_time", - "in": "query", - "description": "Refers start of the time range in unix timestamp when an invalid email was created (inclusive).", - "schema": { - "type": "integer" - } - }, - { - "name": "end_time", - "in": "query", - "description": "Refers end of the time range in unix timestamp when an invalid email was created (inclusive).", - "schema": { - "type": "integer" - } - }, - { - "name": "limit", - "in": "query", - "description": "Limit the number of results to be displayed per page.", - "schema": { - "type": "integer" - } - }, - { - "name": "offset", - "in": "query", - "description": "Paging offset. The point in the list to begin displaying results.", - "schema": { - "type": "integer" - } - }, - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "description": "The list of invalid email addresses.", - "items": { - "$ref": "#/components/schemas/invalid-email" - } - }, - "examples": { - "response": { - "value": [ - { - "created": 1449953655, - "email": "user1@example.com", - "reason": "Mail domain mentioned in email address is unknown" - }, - { - "created": 1449939373, - "email": "user2@example.com", - "reason": "Mail domain mentioned in email address is unknown" - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_suppression-invalidemails", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_suppression-invalid_emails", - "summary": "Delete invalid emails", - "tags": ["Invalid Emails API"], - "description": "**This endpoint allows you to remove email addresses from your invalid email address list.**\n\nThere are two options for deleting invalid email addresses: \n\n1) You can delete all invalid email addresses by setting `delete_all` to true in the request body.\n2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "delete_all": { - "type": "boolean", - "description": "Indicates if you want to remove all email address from the invalid emails list." - }, - "emails": { - "type": "array", - "description": "The list of specific email addresses that you want to remove.", - "items": { - "type": "string", - "format": "email" - } - } - }, - "example": { - "delete_all": false, - "emails": ["example1@example.com", "example2@example.com"] - } - } - } - } - }, - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_suppression-invalidemails", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/suppression/invalid_emails/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "description": "The specific email address of the invalid email entry that you want to retrieve.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_suppression-invalid_emails-email", - "summary": "Retrieve a specific invalid email", - "tags": ["Invalid Emails API"], - "description": "**This endpoint allows you to retrieve a specific invalid email addresses.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "description": "A specific invalid email.", - "minItems": 0, - "maxItems": 1, - "items": { - "$ref": "#/components/schemas/invalid-email" - } - }, - "examples": { - "response": { - "value": [ - { - "created": 1454433146, - "email": "test1@example.com", - "reason": "Mail domain mentioned in email address is unknown" - } - ] - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_suppression-invalidemails-email", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - }, - "delete": { - "operationId": "DELETE_suppression-invalid_emails-email", - "summary": "Delete a specific invalid email", - "tags": ["Invalid Emails API"], - "description": "**This endpoint allows you to remove a specific email address from the invalid email address list.**", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_suppression-invalidemails-email", - "public": true, - "mock": { - "enabled": false, - "statusCode": 200, - "dynamic": false - } - } - } - }, - "/user/webhooks/parse/settings/{hostname}": { - "parameters": [ - { - "name": "hostname", - "in": "path", - "description": "The hostname associated with the inbound parse setting that you would like to retrieve.", - "required": true, - "schema": { - "type": "string" - } - } - ], - "get": { - "operationId": "GET_user-webhooks-parse-settings-hostname", - "summary": "Retrieve a specific parse setting", - "tags": ["Settings - Inbound Parse"], - "description": "**This endpoint allows you to retrieve a specific inbound parse setting by hostname.**\n\nYou can retrieve all your Inbound Parse settings and their associated host names with the \"Retrieve all parse settings\" endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/parse-setting" - }, - "examples": { - "response": { - "value": { - "url": "http://mydomain.com/parse", - "hostname": "mail.mydomain.com", - "spam_check": true, - "send_raw": true - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "GET_user-webhooks-parse-settings-hostname", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - }, - "patch": { - "operationId": "PATCH_user-webhooks-parse-settings-hostname", - "summary": "Update a parse setting", - "tags": ["Settings - Inbound Parse"], - "description": "**This endpoint allows you to update a specific inbound parse setting by hostname.**\n\nYou can retrieve all your Inbound Parse settings and their associated host names with the \"Retrieve all parse settings\" endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "requestBody": { - "$ref": "#/components/requestBodies/parse-setting" - }, - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/parse-setting" - }, - "examples": { - "response": { - "value": { - "url": "http://mydomain.com/parse", - "hostname": "mail.mydomain.com", - "spam_check": true, - "send_raw": true - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "PATCH_user-webhooks-parse-settings-hostname", - "public": true, - "mock": { - "dynamic": false, - "statusCode": 200, - "enabled": false - } - } - }, - "delete": { - "operationId": "DELETE_user-webhooks-parse-settings-hostname", - "summary": "Delete a parse setting", - "tags": ["Settings - Inbound Parse"], - "description": "**This endpoint allows you to delete a specific inbound parse setting by hostname.**\n\nYou can retrieve all your Inbound Parse settings and their associated host names with the \"Retrieve all parse settings\" endpoint.", - "parameters": [ - { - "$ref": "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object" - } - } - } - }, - "401": { - "$ref": "#/components/responses/trait_globalErrors_401" - }, - "403": { - "$ref": "#/components/responses/trait_globalErrors_403" - }, - "404": { - "$ref": "#/components/responses/trait_globalErrors_404" - }, - "500": { - "$ref": "#/components/responses/trait_globalErrors_500" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "x-stoplight": { - "id": "DELETE_user-webhooks-parse-settings-hostname", - "public": true, - "mock": { - "enabled": false, - "dynamic": false, - "statusCode": 200 - } - } - } - } - }, - "x-stoplight": { - "beforeScript": "function (ctx, request) {\n \n request.header.set('User-Agent', 'sendgrid/stoplightdocs');\n \n // REMOVE WITH CAUTION. OR AT LEAST, JUST LEAVE IT COMMENTED OUT.\n // Removing this means your endpoint before scripts will not be run!\n SL.runEndpoint();\n \n //adds the Accept header to every request\n // request.header.set(\"accept\", \"application/json\")\n \n //request.header.set(\"foo\", \"bear\");\n //request.header.add(\"bar\", \"cat\");\n\n // if (request.url.query.get('accept')) {\n // request.header.set('Accept', 'this is a bad header');\n // }\n \n // if (request.url.query.get('behalf')) {\n // request.header.set('on-behalf-of', 'subuser2');\n // }\n \n // For example, adding ?mock=200 to a request url will enable mocking,\n // using the example endpoint response for the 200 status code.\n // var mock = request.url.query.get(\"mock\")\n // if (mock) {\n // ctx.mock.set(true, mock)\n //}\n \n // For example, adding the header X-Mock: 200 will enable mocking,\n // using the example endpoint response for the 200 status code.\n // var mock = request.header.get(\"X-Mock\");\n // if (mock) {\n\t // ctx.mock.set(true, mock);\n\t // ctx.learn.set(false);\n // }\n}", - "afterScript": "function (ctx, request, response) {\n // REMOVE WITH CAUTION. OR AT LEAST, JUST LEAVE IT COMMENTED OUT.\n // Removing this means your endpoint AFTER scripts will not be run!\n SL.runEndpoint();\n \n// if (response.body.get().count() > 1) {\n// request.hijack(200, 'application/json', {foo: 'bear'})\n// }\n\n \n //make this always available\n //SL.utilities.Audit_LogDataInResponse(ctx, request, response);\n \n //if (request.url.query.get('test')) {\n // SL.utilities.RunSpecifiedTests(ctx, request, response);\n //}\n \n // ELMER: Remove this, it logs only DELETE calls\n // if (JSON.parse(request.header.get('X-Mock')) == response.statusCode.get()) {\n // ctx.log.set(false);\n // } else {\n // ctx.log.set(true);\n //}\n}", - "version": { - "groups": { - "docs": [ - { - "divider": true, - "items": [], - "name": "Getting Started" - }, - { - "divider": false, - "items": [ - { - "_id": "api-authentication", - "type": "docTextSections" - }, - { - "_id": "api-authorization", - "type": "docTextSections" - }, - { - "_id": "api-requests", - "type": "docTextSections" - }, - { - "_id": "on-behalf-of", - "type": "docTextSections" - }, - { - "_id": "api-responses", - "type": "docTextSections" - }, - { - "_id": "api-rate-limits", - "type": "docTextSections" - }, - { - "_id": "api-errors", - "type": "docTextSections" - } - ], - "name": "How to use the SendGrid v3 API", - "description": "Welcome to SendGrid’s Web API v3! This API is RESTful, fully featured, easy to integrate with, and offers support in [7 different languages](https://sendgrid.com/docs/for-developers/sending-email/libraries/).\n\n## Libraries\n\n* [C#](https://github.com/sendgrid/sendgrid-csharp)\n* [Go](https://github.com/sendgrid/sendgrid-go)\n* [Java](https://github.com/sendgrid/sendgrid-java)\n* [Node.js](https://github.com/sendgrid/sendgrid-nodejs)\n* [PHP](https://github.com/sendgrid/sendgrid-php)\n* [Python](https://github.com/sendgrid/sendgrid-python)\n* [Ruby](https://github.com/sendgrid/sendgrid-ruby)" - }, - { - "description": "", - "items": [ - { - "_id": "POST_mail-send", - "type": "endpoints" - }, - { - "_id": "mail-send-limitations", - "type": "docTextSections" - }, - { - "_id": "mail-send-validation", - "type": "docTextSections" - }, - { - "_id": "mail-send-errors", - "type": "docTextSections" - }, - { - "_id": "cc_bcc_email_object", - "type": "schemas" - }, - { - "type": "schemas", - "_id": "from_email_object" - }, - { - "_id": "reply_to_email_object", - "type": "schemas" - }, - { - "_id": "to_email_array", - "type": "schemas" - }, - { - "_id": "mailSendErrors", - "type": "traits" - } - ], - "name": "Mail Send", - "divider": false - }, - { - "items": [ - { - "_id": "POST_mail-batch", - "type": "endpoints" - }, - { - "_id": "POST_user-scheduledsends", - "type": "endpoints" - }, - { - "_id": "GET_mail-batch-batchid", - "type": "endpoints" - }, - { - "_id": "GET_user-scheduledsends", - "type": "endpoints" - }, - { - "_id": "GET_user-scheduledsends-batchid", - "type": "endpoints" - }, - { - "_id": "PATCH_user-scheduledsends-batchid", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "DELETE_user-scheduledsends-batchid" - }, - { - "type": "schemas", - "_id": "mail_batch_id" - }, - { - "_id": "user_scheduled_send_status", - "type": "schemas" - }, - { - "_id": "cancelScheduledSendsErrors", - "type": "traits" - } - ], - "name": "Cancel Scheduled Sends", - "description": "The Cancel Scheduled Sends API allows you to cancel or pause the send of one or more emails using a batch ID.\n\nA `batch_id` groups multiple scheduled `mail/send` requests together with the same ID. You can cancel or pause all of the `mail/send` requests associated with a batch ID up to 10 minutes before the scheduled send time by passing a `batch_id` to the \"Cancel or puase a scheduled send\" endpoint.\n\nFor a guide on creating a `batch_id`, assigning it to a scheduled send, and modifying the send, see [\"Canceling a Scheduled Send\"](https://sendgrid.com/docs/for-developers/sending-email/stopping-a-scheduled-send/).\n\nThe Cancel Scheduled Sends API also make it possible to validate a `batch_id` and retrieve all scheduled sends as an array.\n\nWhen a batch is canceled, all messages associated with that batch will stay in your sending queue. When their `send_at` value is reached, they will be discarded.\n\nWhen a batch is paused, all messages associated with that batch will stay in your sending queue, even after their `send_at` value has passed. This means you can remove a `pause` status, and your scheduled send will be delivered once the pause is removed. Any messages left with a `pause` status that are more than 72 hours old will be discarded as Expired.", - "divider": false - }, - { - "divider": true, - "items": [], - "name": "Security" - }, - { - "description": "Your application, mail client, or website can all use API (Application Programming Interface) keys to authenticate access to SendGrid services. You can revoke an API key at any time without having to change your username and password, and an API key can be scoped to perform a limited number of actions.\n\nThere are 3 different types of API keys:\n\n* **Full Access** \nAllows the API key to access `GET`, `PATCH`, `PUT`, `DELETE` and `POST` endpoints for all parts of your account, excluding billing and Email Address Validation.\n* **Restricted Access** \nCustomizes levels of access for all parts of your account, excluding billing and Email Address Validation.\n* **Billing Access** \nAllows the API key to access billing endpoints for the account.\n\nYou must create your first API key using the [Twilio SendGrid App](https://app.sendgrid.com/settings/api_keys). Once you have a key with permissions to manage other keys, you can use the endpoints documented as part of this API.", - "divider": false, - "items": [ - { - "_id": "create-api-keys", - "type": "endpoints" - }, - { - "_id": "GET_apikeys", - "type": "endpoints" - }, - { - "_id": "GET_apikeys-apikeyid", - "type": "endpoints" - }, - { - "_id": "PATCH_apikeys-apikeyid", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "PUT_apikeys-apikeyid" - }, - { - "_id": "DELETE_apikeys-apikeyid", - "type": "endpoints" - }, - { - "_id": "api_key_name_id", - "type": "schemas" - }, - { - "_id": "api_key_name_id_scopes", - "type": "schemas" - }, - { - "_id": "apiKeysErrors", - "type": "traits" - } - ], - "name": "API Keys" - }, - { - "name": "API Key Permissions", - "divider": false, - "items": [ - { - "_id": "api-key-permissions", - "type": "docTextSections" - }, - { - "_id": "GET_scopes", - "type": "endpoints" - } - ] - }, - { - "items": [ - { - "_id": "GET_user-settings-enforcedtls", - "type": "endpoints" - }, - { - "_id": "PATCH_user-settings-enforcedtls", - "type": "endpoints" - }, - { - "_id": "enforced-tls-request-response", - "type": "schemas" - } - ], - "name": "Settings - Enforced TLS", - "description": "The Enforced TLS settings specify whether or not the recipient of your send is required to support TLS or have a valid certificate. The Enforced TLS endpoint supports retrieving and updating TLS settings.\n\nTwilio SendGrid sends all emails with [Opportunistic TLS](https://sendgrid.com/blog/myth-opportunistic-tls-email-privacy/) by default, meaning email is sent with TLS, and if the recipient's inbox provider does not accept the TLS encryption, we then send the message unencrypted.\n\nYou can optionally choose to enforce TLS encryption, meaning that if the recipient's inbox provider does not accept the TLS encryption, Twilio SendGrid drops the message and sends a block event with “TLS required but not supported” as the description.", - "divider": false - }, - { - "items": [ - { - "_id": "POST_accesssettings-whitelist", - "type": "endpoints" - }, - { - "_id": "GET_accesssettings-activity", - "type": "endpoints" - }, - { - "_id": "GET_accesssettings-whitelist", - "type": "endpoints" - }, - { - "_id": "GET_accesssettings-whitelist-ruleid", - "type": "endpoints" - }, - { - "_id": "DELETE_accesssettings-whitelist", - "type": "endpoints" - }, - { - "_id": "DELETE_accesssettings-whitelist-ruleid", - "type": "endpoints" - }, - { - "_id": "ip-access-response", - "type": "schemas" - } - ], - "name": "IP Access Management", - "divider": false, - "description": "IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API.\n\nThere is no limit to the number of IP addresses that you can allow.\n\n> It is possible to remove your own IP address from your list of allowed addresses, thus blocking your own access to your account. While we are able to restore your access, we do require thorough proof of your identify and ownership of your account. We take the security of your account very seriously, and wish to prevent any 'bad actors' from maliciously gaining access to your account.\n>\n> Your current IP is clearly displayed to help prevent you from accidentally removing it from the allowed addresses.\n\nFor more information, please see our [IP Access Management documentation](https://sendgrid.com/docs/ui/account-and-settings/ip-access-management/)." - }, - { - "divider": true, - "items": [], - "name": "Single Sign-On" - }, - { - "divider": false, - "items": [ - { - "_id": "sso-error-response", - "type": "schemas" - }, - { - "_id": "singleSignOnErrorsTrait", - "type": "traits" - } - ], - "name": "Single Sign-On Shared Models and Traits" - }, - { - "divider": false, - "items": [ - { - "_id": "POST_sso-certificates", - "type": "endpoints" - }, - { - "_id": "GET_sso-integrations-integrationid-certificates", - "type": "endpoints" - }, - { - "_id": "GET_sso-certificates-certid", - "type": "endpoints" - }, - { - "_id": "PATCH_sso-certificates-certid", - "type": "endpoints" - }, - { - "_id": "DELETE_sso-certificates-certid", - "type": "endpoints" - }, - { - "_id": "sso-certificate-body", - "type": "schemas" - } - ], - "name": "Certificates", - "description": ">Twilio SendGrid Single Sign-On is currently in beta. The following documentation and product interface may change as the product is improved.\n>\n>**Known limitations during beta** \nTwilio SendGrid SSO does not currently support granting an SSO user access to more than one Subuser without granting the SSO user administrator access at the top level of your Twilio SendGrid account.\n\nThe Single Sign-On APIs allow you to manage your SAML 2.0 SSO configurations. You can also work with your SSO integrations using the [SSO section of the Twilio SendGrid App](https://app.sendgrid.com/settings/sso).\n\nThe Certificates API allows you to create, modify, and delete SSO certificates. A SAML certificate allows your IdP and Twilio SendGrid to verify requests are coming from one another using the `public_certificate` and `integration_id` parameters.\n\nFor more information about managing SSO Certificates, see the [Twilio SendGrid SSO documentation](https://sendgrid.com/docs/ui/account-and-settings/sso/)." - }, - { - "divider": false, - "items": [ - { - "_id": "POST_sso-integrations", - "type": "endpoints" - }, - { - "_id": "GET_sso-integrations", - "type": "endpoints" - }, - { - "_id": "GET_sso-integrations-id", - "type": "endpoints" - }, - { - "_id": "PATCH_sso-integrations-id", - "type": "endpoints" - }, - { - "_id": "DELETE_sso-integrations-id", - "type": "endpoints" - }, - { - "_id": "create-integration-request", - "type": "schemas" - }, - { - "_id": "sso-integration", - "type": "schemas" - } - ], - "name": "Single Sign-On Settings", - "description": ">Twilio SendGrid Single Sign-On is currently in beta. The following documentation and product interface may change as the product is improved.\n>\n>**Known limitations during beta** \nTwilio SendGrid SSO does not currently support granting an SSO user access to more than one Subuser without granting the SSO user administrator access at the top level of your Twilio SendGrid account.\n\nThe Single Sign-On APIs allow you to manage your SAML 2.0 SSO configurations. You can also work with your SSO integrations using the [SSO section of the Twilio SendGrid App](https://app.sendgrid.com/settings/sso).\n\nThe Single Sign-On Settings API allows you to create, retrieve, modify, and delete SSO integrations for your Twilio SendGrid account. Each integration will correspond to a specific IdP such as Okta, Duo, or Microsoft Azure Active Directory.\n\n" - }, - { - "divider": false, - "items": [ - { - "_id": "POST_sso-teammates", - "type": "endpoints" - }, - { - "_id": "PATCH_sso-teammates-username", - "type": "endpoints" - }, - { - "_id": "sso-teammate-common-fields", - "type": "schemas" - }, - { - "_id": "sso-teammate-request", - "type": "schemas" - }, - { - "_id": "sso-teammate-response", - "type": "schemas" - }, - { - "_id": "sso-teammates-patch-response", - "type": "schemas" - } - ], - "name": "Single Sign-On Teammates", - "description": ">Twilio SendGrid Single Sign-On is currently in beta. The following documentation and product interface may change as the product is improved.\n>\n>**Known limitations during beta** \nTwilio SendGrid SSO does not currently support granting an SSO user access to more than one Subuser without granting the SSO user administrator access at the top level of your Twilio SendGrid account.\n\nThe Single Sign-On APIs allow you to manage your SAML 2.0 SSO configurations. You can also work with your SSO integrations using the [SSO section of the Twilio SendGrid App](https://app.sendgrid.com/settings/sso).\n\nThe Single Sign-On Teammates API allows you to add and modify SSO Teammates. SSO Teammates are the individual user accounts who will access your Twilio SendGrid account with SSO credentials.\n\nTo retrieve or delete an SSO Teammate, you will use the [Teammates API](https://sendgrid.api-docs.io/v3.0/teammates). \n\nFor more information about managing SSO Teammates, see the [Twilio SendGrid SSO documentation](https://sendgrid.com/docs/ui/account-and-settings/sso/#manage-users)." - }, - { - "divider": true, - "items": [], - "name": "Settings" - }, - { - "items": [ - { - "type": "endpoints", - "_id": "GET_mailsettings" - }, - { - "_id": "PATCH_mailsettings-addresswhitelist", - "type": "endpoints" - }, - { - "_id": "GET_mailsettings-addresswhitelist", - "type": "endpoints" - }, - { - "_id": "PATCH_mailsettings-footer", - "type": "endpoints" - }, - { - "_id": "GET_mailsettings-footer", - "type": "endpoints" - }, - { - "_id": "PATCH_mailsettings-forwardspam", - "type": "endpoints" - }, - { - "_id": "GET_mailsettings-forwardspam", - "type": "endpoints" - }, - { - "_id": "PATCH_mailsettings-template", - "type": "endpoints" - }, - { - "_id": "GET_mailsettings-template", - "type": "endpoints" - }, - { - "_id": "PATCH_mailsettings-bouncepurge", - "type": "endpoints" - }, - { - "_id": "GET_mailsettings-bouncepurge", - "type": "endpoints" - }, - { - "_id": "PATCH_mailsettings-forwardbounce", - "type": "endpoints" - }, - { - "_id": "GET_mailsettings-forwardbounce", - "type": "endpoints" - }, - { - "_id": "mail_settings_patch", - "type": "schemas" - }, - { - "_id": "mail_settings_address_whitelabel", - "type": "schemas" - }, - { - "_id": "mail_settings_footer", - "type": "schemas" - }, - { - "type": "schemas", - "_id": "mail_settings_forward_spam" - }, - { - "_id": "mail_settings_template", - "type": "schemas" - }, - { - "_id": "mail_settings_bounce_purge", - "type": "schemas" - }, - { - "_id": "mail_settings_forward_bounce", - "type": "schemas" - } - ], - "name": "Settings - Mail", - "description": "Mail Settings instruct SendGrid to apply specific settings to every email that you send over [SendGrid’s v3 API](https://sendgrid.api-docs.io/v3.0/mail-send/v3-mail-send) or [SMTP Relay](https://sendgrid.com/docs/for-developers/sending-email/building-an-x-smtpapi-header/). These settings include how to embed a custom footer, how to manage blocks, spam, and bounces, and more.\n\nFor a full list of Twilio SendGrid's Mail Settings, and what each one does, see our [Mail Settings documentation](https://sendgrid.com/docs/ui/account-and-settings/mail/).\n\nYou can also manage your Mail Settings in the [Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings)", - "divider": false - }, - { - "divider": false, - "items": [ - { - "_id": "PATCH_partnersettings-newrelic", - "type": "endpoints" - }, - { - "_id": "GET_partnersettings-newrelic", - "type": "endpoints" - }, - { - "_id": "GET_partnersettings", - "type": "endpoints" - }, - { - "_id": "partner_settings_new_relic", - "type": "schemas" - } - ], - "name": "Settings - Partner", - "description": "Elements that can be shared among more than one endpoint definition." - }, - { - "divider": false, - "items": [ - { - "_id": "POST_v3-teammates", - "type": "endpoints" - }, - { - "_id": "POST_v3-teammates-pending-token-resend", - "type": "endpoints" - }, - { - "_id": "GET_v3-teammates", - "type": "endpoints" - }, - { - "_id": "GET_v3-scopes-requests", - "type": "endpoints" - }, - { - "_id": "GET_v3-teammates-pending", - "type": "endpoints" - }, - { - "_id": "GET_v3-teammates-username", - "type": "endpoints" - }, - { - "_id": "PATCH_v3-scopes-requests-approve-id", - "type": "endpoints" - }, - { - "_id": "PATCH_v3-teammates-username", - "type": "endpoints" - }, - { - "_id": "DELETE_v3-scopes-requests-request_id", - "type": "endpoints" - }, - { - "_id": "DELETE_v3-teammates-pending-token", - "type": "endpoints" - }, - { - "_id": "DELETE_v3-teammates-username", - "type": "endpoints" - } - ], - "name": "Teammates", - "description": "Give and adjust account access." - }, - { - "name": "Alerts", - "items": [ - { - "_id": "POST_alerts", - "type": "endpoints" - }, - { - "_id": "GET_alerts", - "type": "endpoints" - }, - { - "_id": "GET_alerts-alertid", - "type": "endpoints" - }, - { - "_id": "DELETE_alerts-alertid", - "type": "endpoints" - }, - { - "_id": "PATCH_alerts-alertid", - "type": "endpoints" - } - ], - "divider": false, - "description": "Elements that can be shared among more than one endpoint definition." - }, - { - "items": [ - { - "_id": "user_profile", - "type": "schemas" - }, - { - "_id": "GET_user-profile", - "type": "endpoints" - }, - { - "_id": "PATCH_user-profile", - "type": "endpoints" - }, - { - "_id": "GET_user-account", - "type": "endpoints" - }, - { - "_id": "GET_user-email", - "type": "endpoints" - }, - { - "_id": "PUT_user-email", - "type": "endpoints" - }, - { - "_id": "GET_user-username", - "type": "endpoints" - }, - { - "_id": "PUT_user-username", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "GET_user-credits" - }, - { - "_id": "PUT_user-password", - "type": "endpoints" - } - ], - "name": "Users API", - "description": "Keeping your user profile up to date helps SendGrid verify who you are and share important communications with you.\n\nYou can learn more in the [SendGrid Account Details documentation.](https://sendgrid.com/docs/ui/account-and-settings/account/)", - "divider": false - }, - { - "items": [ - { - "type": "schemas", - "_id": "subuser" - }, - { - "_id": "subuser_post", - "type": "schemas" - }, - { - "type": "endpoints", - "_id": "GET_subusers" - }, - { - "_id": "POST_subusers", - "type": "endpoints" - }, - { - "_id": "PATCH_subusers-subusername", - "type": "endpoints" - }, - { - "_id": "DELETE_subusers-subusername", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "GET_subusers-reputations" - }, - { - "_id": "PUT_subusers-subusername-ips", - "type": "endpoints" - } - ], - "name": "Subusers API", - "description": "For more information about Subusers, visit the [longform Subusers documentation](https://sendgrid.com/docs/ui/account-and-settings/subusers/). You can also [manage Subusers in the SendGrid console](https://app.sendgrid.com/settings/subusers).", - "divider": false - }, - { - "divider": false, - "items": [ - { - "_id": "monitor", - "type": "schemas" - }, - { - "_id": "GET_subusers-subusername-monitor", - "type": "endpoints" - }, - { - "_id": "POST_subusers-subusername-monitor", - "type": "endpoints" - }, - { - "_id": "PUT_subusers-subusername-monitor", - "type": "endpoints" - }, - { - "_id": "DELETE_subusers-subusername-monitor", - "type": "endpoints" - } - ], - "name": "Subuser Monitor Settings", - "description": "Subuser monitor settings allow you to receive a sample of an outgoing message from a specific customer at a specific frequency of emails." - }, - { - "divider": false, - "items": [ - { - "_id": "subuser_stats", - "type": "schemas" - }, - { - "_id": "GET_subusers-subusername-stats-monthly", - "type": "endpoints" - }, - { - "_id": "GET_subusers-stats-monthly", - "type": "endpoints" - }, - { - "_id": "GET_subusers-stats-sums", - "type": "endpoints" - }, - { - "_id": "GET_subusers-stats", - "type": "endpoints" - } - ], - "name": "Subuser Statistics", - "description": "Subuser statistics enable you to view specific segments of your statistics, as compared to the general overview of all email activity on your account. SendGrid tracks your subusers' emails sent, bounces, and spam reports. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\n\nFor more information, see our [Subusers documentation](https://sendgrid.com/docs/ui/account-and-settings/subusers/). You can also access [Subuser Statistics in the SendGrid console](https://app.sendgrid.com/statistics/subuser)." - }, - { - "divider": true, - "items": [], - "name": "Deliverability" - }, - { - "name": "Link branding", - "items": [ - { - "_id": "POST_whitelabel-links", - "type": "endpoints" - }, - { - "_id": "POST_whitelabel-links-id-validate", - "type": "endpoints" - }, - { - "_id": "POST_whitelabel-links-linkid-subuser", - "type": "endpoints" - }, - { - "_id": "GET_whitelabel-links", - "type": "endpoints" - }, - { - "_id": "GET_whitelabel-links-id", - "type": "endpoints" - }, - { - "_id": "GET_whitelabel-links-default", - "type": "endpoints" - }, - { - "_id": "GET_whitelabel-links-subuser", - "type": "endpoints" - }, - { - "_id": "PATCH_whitelabel-links-id", - "type": "endpoints" - }, - { - "_id": "DELETE_whitelabel-links-id", - "type": "endpoints" - }, - { - "_id": "DELETE_whitelabel-links-subuser", - "type": "endpoints" - }, - { - "_id": "link_branding_200_response", - "type": "schemas" - } - ], - "description": "Email link branding (formerly \"Link Whitelabel\") allows all of the click-tracked links, opens, and images in your emails to be served from your domain rather than `sendgrid.net`. Spam filters and recipient servers look at the links within emails to determine whether the email looks trustworthy. They use the reputation of the root domain to determine whether the links can be trusted.\n\nYou can also manage link branding in the [Sender Authentication section of the Twilio SendGrid App](https://app.sendgrid.com/settings/sender_auth).\n\nFor more information, please see our [Link Branding documentation](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/).", - "divider": false - }, - { - "name": "IP Warmup", - "items": [ - { - "_id": "POST_ips-warmup", - "type": "endpoints" - }, - { - "_id": "GET_ips-warmup", - "type": "endpoints" - }, - { - "_id": "GET_ips-warmup-ipaddress", - "type": "endpoints" - }, - { - "_id": "DELETE_ips-warmup-ipaddress", - "type": "endpoints" - }, - { - "type": "schemas", - "_id": "ip_warmup_response" - } - ], - "description": "IP warming is the practice of gradually increasing the volume of mail sent with a dedicated IP address according to a predetermined schedule. This gradual process helps to establish a reputation with ISPs (Internet Service Providers) as a legitimate email sender.\n\nSendGrid can automatically [warm up](https://sendgrid.com/docs/glossary/ip-warmup/) dedicated IP addresses by limiting the amount of mail that can be sent through them per hour. The limit determined by how long the IP address has been warming up. \n\nSee the [warmup schedule](https://sendgrid.com/docs/ui/sending-email/warming-up-an-ip-address/#automated-ip-warmup-hourly-send-schedule) to learn how SendGrid limits your email traffic for IPs in warmup.\n\nYou can also choose to use Twilio SendGrid's automated IP warmup for any of your IPs from the [\"IP Addresses\" settings menu in the Twilio SendGrid App](https://app.sendgrid.com/settings/ip_addresses).", - "divider": false - }, - { - "items": [ - { - "_id": "POST_whitelabel-ips", - "type": "endpoints" - }, - { - "_id": "POST_whitelabel-ips-id-validate", - "type": "endpoints" - }, - { - "_id": "GET_whitelabel-ips", - "type": "endpoints" - }, - { - "_id": "GET_whitelabel-ips-id", - "type": "endpoints" - }, - { - "_id": "DELETE_whitelabel-ips-id", - "type": "endpoints" - }, - { - "type": "schemas", - "_id": "reverse_dns" - } - ], - "name": "Reverse DNS", - "description": "Reverse DNS (formerly IP Whitelabel) allows mailbox providers to verify the sender of an email by performing a reverse DNS lookup upon receipt of the emails you send.\n\nReverse DNS is available for [dedicated IP addresses](https://sendgrid.com/docs/ui/account-and-settings/dedicated-ip-addresses/) only.\n\nWhen setting up reverse DNS, Twilio SendGrid will provide an A Record (address record) for you to add to your DNS records. The A Record maps your sending domain to a dedicated Twilio SendGrid IP address.\n\nA Reverse DNS consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP address. Once Twilio SendGrid has verified that the appropriate A record for the IP address has been created, the appropriate reverse DNS record for the IP address is generated.\n\nYou can also manage your reverse DNS settings in the [Sender Authentication setion of the Twilio SendGrid App](https://app.sendgrid.com/settings/sender_auth).\n\nFor more about Reverse DNS, see [\"How to set up reverse DNS\"](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/) in the Twilio SendGrid documentation.", - "divider": false - }, - { - "divider": false, - "items": [ - { - "_id": "POST_validations-email", - "type": "endpoints" - } - ], - "name": "Email Address Validation", - "description": "**Email Address Validation is available to Email API Pro and Premier level accounts only. Prior to upgrading your account to Pro or Premier, you will not see the option to create an Email Validation API key. An Email Validation API key is separate from and in addition to your other keys, including a Full Access API key.**\n\nEmail Address Validation provides real-time detailed information on the validity of email addresses. You can integrate this validation process into your platform's signup form and customize the best use of email address validation for your use case.\n\nYou can use this API to:\n\n* Indicate to users that the address they have entered into a form is invalid.\n* Drop invalid email addresses from your database.\n* [Suppress invalid email addresses](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#different-types-of-suppressions) from your sending to decrease your bounce rate.\n\nYou can learn more about enabling Email Validation in our [Email Validation documentation](https://sendgrid.com/docs/ui/managing-contacts/email-address-validation/).\n\nYou can also view your Email Validation results and metrics in the [Validation section of the Twilio SendGrid App](https://app.sendgrid.com/email_validation). Again, these settings are available only after upgrading your account to Pro or higher." - }, - { - "divider": false, - "items": [ - { - "_id": "POST_whitelabel-dns-email", - "type": "endpoints" - } - ], - "name": "Email CNAME records", - "description": "If you don't have access to modify your companies DNS records, you can email the records to a co-worker who does to complete [Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) and/or [Link Branding](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/) setups. This email includes a direct link to the DNS records. The link does expire, but the recipient doesn't need login access to your Twilio SendGrid account.\n" - }, - { - "items": [ - { - "_id": "POST_ips-pools", - "type": "endpoints" - }, - { - "_id": "POST_ips-pools-poolname-ips", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "GET_ips-pools" - }, - { - "_id": "GET_ips-pools-poolname", - "type": "endpoints" - }, - { - "_id": "PUT_ips-pools-poolname", - "type": "endpoints" - }, - { - "_id": "DELETE_ips-pools-poolname", - "type": "endpoints" - }, - { - "_id": "DELETE_ips-pools-poolname-ips-ip", - "type": "endpoints" - }, - { - "_id": "ip_pool", - "type": "schemas" - }, - { - "_id": "ip_pool_response", - "type": "schemas" - } - ], - "name": "IP Pools", - "description": "IP pools allow you to group your dedicated SendGrid IP addresses. For example, you could create separate one pool for your transactional email and another for your marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.\n\nIP pools can only be used with IP addresses for which you’ve set up a reverse DNS record.\n\nIf an IP pool is *not* specified for an email, it will use any IP available, including pooled addresses.\n\n**Each user can create up to 10 different IP pools.**", - "divider": false - }, - { - "items": [ - { - "_id": "POST_ips", - "type": "endpoints" - }, - { - "_id": "GET_ips-remaining", - "type": "endpoints" - }, - { - "_id": "GET_ips", - "type": "endpoints" - }, - { - "_id": "GET_ips-assigned", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "GET_ips-ipaddress" - } - ], - "name": "IP Addresses", - "description": "Elements that can be shared among more than one endpoint definition.", - "divider": false - }, - { - "description": "An authenticated domain allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will get 2 TXT records and 1 MX record.\n\nDomain Authentication was formerly called \"Domain Whitelabel\".\n\nFor more information, please see [How to set up domain authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/).", - "divider": false, - "items": [ - { - "_id": "domain_authentication:domain_spf", - "type": "schemas" - }, - { - "_id": "authentication::domain", - "type": "schemas" - }, - { - "_id": "domain-authentication-200-response", - "type": "schemas" - }, - { - "type": "endpoints", - "_id": "GET_whitelabel-domains" - }, - { - "_id": "GET_whitelabel-domains-domainid", - "type": "endpoints" - }, - { - "_id": "POST_whitelabel-domains", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "PATCH_whitelabel-domains-domainid" - }, - { - "_id": "DELETE_whitelabel-domains-domainid", - "type": "endpoints" - }, - { - "_id": "GET_whitelabel-domains-default", - "type": "endpoints" - }, - { - "_id": "POST_whitelabel-domains-id-ips", - "type": "endpoints" - }, - { - "_id": "DELETE_whitelabel-domains-id-ips-ip", - "type": "endpoints" - }, - { - "_id": "POST_whitelabel-domains-id-validate", - "type": "endpoints" - }, - { - "_id": "GET_whitelabel-domains-subuser", - "type": "endpoints" - }, - { - "_id": "DELETE_whitelabel-domains-subuser", - "type": "endpoints" - }, - { - "_id": "POST_whitelabel-domains-domainid-subuser", - "type": "endpoints" - } - ], - "name": "Domain Authentication" - }, - { - "divider": false, - "items": [ - { - "_id": "GET_verifiedsenders-domains", - "type": "endpoints" - }, - { - "_id": "GET_verifiedsenders-stepscompleted", - "type": "endpoints" - }, - { - "_id": "POST_verifiedsenders", - "type": "endpoints" - }, - { - "_id": "GET_verifiedsenders-verify-token", - "type": "endpoints" - }, - { - "_id": "PATCH_verifiedsenders-id", - "type": "endpoints" - }, - { - "_id": "DELETE_verifiedsenders-id", - "type": "endpoints" - }, - { - "_id": "GET_verifiedsenders", - "type": "endpoints" - }, - { - "_id": "POST_verifiedsenders-resend-id", - "type": "endpoints" - }, - { - "_id": "verified-sender-request-schema", - "type": "schemas" - }, - { - "_id": "verified-sender-response-schema", - "type": "schemas" - } - ], - "name": "Sender Verification", - "description": "The Sender Verification API exposes multiple endpoints that allow you to programmatically manage the [Sender Identities](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/) that are authorized to send email for your account.\nYou can also manage Sender Identities in the SendGrid app by selecting [**Sender Authentication** under **Settings** in the navigation bar](https://app.sendgrid.com/settings/sender_auth). For full app instructions, see [Sender Verification](https://sendgrid.com/docs/ui/sending-email/sender-verification/).\n\nThe Sender Verification API provides a RESTful interface for creating new Sender Identities, retrieving a list of existing Sender Identities, checking the status of a Sender Identity, updating a Sender Identity, and deleting a Sender Identity.\n \nThis API offers additional endpoints to check for domains known to implement DMARC, and resend verification emails to Sender Identities that have yet to complete the verification process." - }, - { - "divider": true, - "items": [], - "name": "Design Library" - }, - { - "divider": false, - "items": [ - { - "_id": "_metadata", - "type": "schemas" - }, - { - "_id": "api-error", - "type": "schemas" - }, - { - "_id": "api-errors", - "type": "schemas" - }, - { - "_id": "design-duplicate-input", - "type": "schemas" - }, - { - "_id": "design-common-fields", - "type": "schemas" - }, - { - "_id": "design-input", - "type": "schemas" - }, - { - "_id": "design-output-summary", - "type": "schemas" - }, - { - "_id": "design-output", - "type": "schemas" - }, - { - "_id": "designsQueryStrings", - "type": "traits" - }, - { - "_id": "POST-design", - "type": "endpoints" - }, - { - "_id": "POST-design", - "type": "endpoints" - }, - { - "_id": "LIST-designs", - "type": "endpoints" - }, - { - "_id": "GET-design", - "type": "endpoints" - }, - { - "_id": "POST-sendgrid-pre-built-design", - "type": "endpoints" - }, - { - "_id": "LIST-Sendgrid-Pre-built-designs", - "type": "endpoints" - }, - { - "_id": "GET-sendgrid-pre-built-design", - "type": "endpoints" - }, - { - "_id": "PUT-design", - "type": "endpoints" - }, - { - "_id": "DELETE-design", - "type": "endpoints" - } - ], - "name": "Designs API", - "description": "The Designs API offers the ability to manage assets stored in the Twilio SendGrid [Design Library](https://mc.sendgrid.com/design-library/my-designs).\n\nThe Design Library is a feature-rich email layout tool and media repository. You can [build designs for all your email needs](https://sendgrid.com/docs/ui/sending-email/working-with-marketing-campaigns-email-designs/), including Single Sends, Automations, and Dynamic Templates.\n\nYou can also duplicate and then modify one of the pre-built designs provided by Twilio SendGrid to get you started.\n\nThe Designs API provides a RESTful interface for creating new designs, retrieving a list of existing designs, duplicating or updating a design, and deleting a design." - }, - { - "divider": true, - "items": [], - "name": "New Marketing Campaigns" - }, - { - "divider": false, - "items": [ - { - "_id": "contact-import", - "type": "schemas" - }, - { - "_id": "single-contact-request", - "type": "schemas" - }, - { - "_id": "contact-export", - "type": "schemas" - }, - { - "_id": "contact-summary", - "type": "schemas" - }, - { - "_id": "contact-request", - "type": "schemas" - }, - { - "_id": "contact-details", - "type": "schemas" - }, - { - "_id": "contact-details2", - "type": "schemas" - }, - { - "_id": "contact-details3", - "type": "schemas" - }, - { - "_id": "PUT_mc-contacts", - "type": "endpoints" - }, - { - "_id": "DELETE_mc-contacts", - "type": "endpoints" - }, - { - "_id": "GET_mc-contacts-count", - "type": "endpoints" - }, - { - "_id": "POST_mc-contacts-exports", - "type": "endpoints" - }, - { - "_id": "GET_mc-contacts-id", - "type": "endpoints" - }, - { - "_id": "POST_mc-contacts-search", - "type": "endpoints" - }, - { - "_id": "GET_mc-contats", - "type": "endpoints" - }, - { - "_id": "PUT_mc-contacts-imports", - "type": "endpoints" - }, - { - "_id": "GET_marketing-contacts-imports-id", - "type": "endpoints" - }, - { - "_id": "GET_mc-contacts-exports-id", - "type": "endpoints" - }, - { - "_id": "GET_marketing-contacts-exports", - "type": "endpoints" - }, - { - "_id": "POST_marketing-contacts-batch", - "type": "endpoints" - }, - { - "_id": "POST_marketing-contacts-search-emails", - "type": "endpoints" - }, - { - "_id": "tip", - "type": "docTextSections" - } - ], - "name": "Contacts" - }, - { - "divider": false, - "items": [ - { - "_id": "segment_status_response", - "type": "schemas" - }, - { - "_id": "all_segments_response", - "type": "schemas" - }, - { - "_id": "segment_summary_v2", - "type": "schemas" - }, - { - "_id": "contact_response", - "type": "schemas" - }, - { - "_id": "segment_response", - "type": "schemas" - }, - { - "_id": "errors-seg-v2", - "type": "schemas" - }, - { - "_id": "segment_write_v2", - "type": "schemas" - }, - { - "_id": "segment_update", - "type": "schemas" - }, - { - "_id": "_metadata", - "type": "schemas" - }, - { - "_id": "POST_segments", - "type": "endpoints" - }, - { - "_id": "errors", - "type": "traits" - }, - { - "_id": "PATCH_segments-segment_id", - "type": "endpoints" - }, - { - "_id": "GET_segments", - "type": "endpoints" - }, - { - "_id": "GET_segments-segment_id", - "type": "endpoints" - }, - { - "_id": "DELETE_segments-segment_id", - "type": "endpoints" - } - ], - "name": "Segmenting Contacts V2 - Beta" - }, - { - "divider": false, - "items": [ - { - "_id": "senders-id-request-body", - "type": "schemas" - }, - { - "_id": "TNE-senderID", - "type": "schemas" - }, - { - "_id": "POST_marketing-senders", - "type": "endpoints" - } - ], - "name": "Senders" - }, - { - "divider": false, - "items": [ - { - "_id": "list", - "type": "schemas" - }, - { - "_id": "POST_mc-lists", - "type": "endpoints" - }, - { - "_id": "GET_mc-lists-id-contacts-count", - "type": "endpoints" - }, - { - "_id": "GET_mc-lists-id", - "type": "endpoints" - }, - { - "_id": "GET_mc-lists", - "type": "endpoints" - }, - { - "_id": "PATCH_mc-lists-id", - "type": "endpoints" - }, - { - "_id": "DELETE_lists-id", - "type": "endpoints" - }, - { - "_id": "DELETE_mc-lists-id-contacts", - "type": "endpoints" - } - ], - "name": "Lists", - "description": "Lists are static collections of Marketing Campaigns contacts. This API allows you to interact with the list objects themselves. To add contacts to a list, you must use the [Contacts API](https://sendgrid.api-docs.io/v3.0/contacts).\n\nYou can also manage your lists using the [Contacts menu in the Marketing Campaigns UI](https://mc.sendgrid.com/contacts). For more information about lists and best practices for building them, see [\"Building your Contact List\"](https://sendgrid.com/docs/ui/managing-contacts/building-your-contact-list/)." - }, - { - "divider": false, - "items": [ - { - "_id": "custom-fields-by-name", - "type": "schemas" - }, - { - "_id": "custom-fields-by-id", - "type": "schemas" - }, - { - "_id": "reserved_field_definitions_response", - "type": "schemas" - }, - { - "_id": "custom_field_definitions_response", - "type": "schemas" - }, - { - "_id": "POST_mc-field_definitions", - "type": "endpoints" - }, - { - "_id": "GET_mc-field_definitions", - "type": "endpoints" - }, - { - "_id": "PATCH_mc-field_definitions-custom_field_id", - "type": "endpoints" - }, - { - "_id": "DELETE_mc-field_definitions-custom_field_id", - "type": "endpoints" - } - ], - "name": "Custom Fields", - "description": "Custom Fields allow you to add extra information about your contacts to your contact database. With custom fields, you can create custom segments from your individual contacts or from your contact database that will dynamically update your content with the values for the individual contact receiving the email. Your custom fields are completely customizable to the use cases and user information that you need.\n\nYou can also manage your Custom Fields using the [Custom Fields UI in the Marketing Campaigns App](https://mc.sendgrid.com/custom-fields). For more about creating Custom Fields, including a list of Reserved Fields, see our [Custom Fields documentation](https://sendgrid.com/docs/ui/managing-contacts/custom-fields/)." - }, - { - "divider": false, - "items": [ - { - "_id": "xJZx99h8rizghwRct", - "type": "traits" - }, - { - "_id": "segment_write", - "type": "schemas" - }, - { - "_id": "contact_response", - "type": "schemas" - }, - { - "_id": "segment_summary", - "type": "schemas" - }, - { - "_id": "full-segment", - "type": "schemas" - }, - { - "_id": "segment_query_json", - "type": "schemas" - }, - { - "_id": "POST_marketing-segments", - "type": "endpoints" - }, - { - "_id": "GET_marketing-segments-segmentid", - "type": "endpoints" - }, - { - "_id": "GET_marketing-segments", - "type": "endpoints" - }, - { - "_id": "PATCH_marketing-segments-segmentid", - "type": "endpoints" - }, - { - "_id": "DELETE_marketing-segments-segmentid", - "type": "endpoints" - }, - { - "_id": "POST_marketing-segments-delete", - "type": "endpoints" - } - ], - "name": "Segmenting Contacts", - "description": "Segments are similar to contact lists, except they update dynamically over time as information stored about your contacts or the criteria used to define your segments changes. When you segment your audience, you are able to create personalized Automation emails and Single Sends that directly address the wants and needs of your particular audience.\n\nThe Marketing Campaigns Segments API allows you to create, edit, and delete segments as well as retrieve a list of segments or an individual segment by ID.\n\n> Note that Twilio SendGrid checks for newly added or modified contacts who meet a segment's criteria on an hourly schedule. Only existing contacts who meet a segment's criteria will be included in the segment searches within 15 minutes.\n>\n> Segments built using engagement data such as \"was sent\" or \"clicked\" will take approximately 30 minutes to begin populating.\n>\n> Segment samples and counts are refreshed approximately once per hour; they do not update immediately. If no contacts are added to or removed from a segment since the last refresh, the sample and UI count displayed will be refreshed at increasing time intervals with a maximum sample and count refresh delay of 24 hours.\n\nFor more information on creating segments with the Twilio SendGrid Marketing Campaigns UI see [\"Segmenting your Contacts.\"](https://sendgrid.com/docs/ui/managing-contacts/segmenting-your-contacts/)\n\nFor help with Segmentation Query Language, see our [Segmentation Query Language reference](https://sendgrid.com/docs/for-developers/sending-email/segmentation-query-language/)" - }, - { - "divider": false, - "items": [ - { - "_id": "vve7kMhgurSwPWi6S", - "type": "schemas" - }, - { - "_id": "FTA2YcjxEPyAFfYe8", - "type": "schemas" - }, - { - "_id": "singlesend_request", - "type": "schemas" - }, - { - "_id": "singlesend_response_short", - "type": "schemas" - }, - { - "_id": "singlesend_response", - "type": "schemas" - }, - { - "_id": "singlesend_search", - "type": "schemas" - }, - { - "_id": "singlesend_schedule", - "type": "schemas" - }, - { - "_id": "singlesend_warning", - "type": "schemas" - }, - { - "_id": "abtest_summary", - "type": "schemas" - }, - { - "_id": "POST_marketing-singlesends", - "type": "endpoints" - }, - { - "_id": "POST_marketing-singlesends-id", - "type": "endpoints" - }, - { - "_id": "POST_marketing-singlesends-search", - "type": "endpoints" - }, - { - "_id": "PATCH_marketing-singlesends-id", - "type": "endpoints" - }, - { - "_id": "PUT_marketing-singlesends-id-schedule", - "type": "endpoints" - }, - { - "_id": "GET_marketing-singlesends", - "type": "endpoints" - }, - { - "_id": "GET_marketing-singlesends-id", - "type": "endpoints" - }, - { - "_id": "GET_marketing-singlesends-categories", - "type": "endpoints" - }, - { - "_id": "DELETE_marketing-singlesends-id", - "type": "endpoints" - }, - { - "_id": "DELETE_marketing-singlesends", - "type": "endpoints" - }, - { - "_id": "DELETE_marketing-singlesends-id-schedule", - "type": "endpoints" - } - ], - "name": "Single Sends", - "description": "A Single Send is a one-time nonautomated email message delivered to a list or segment of your audience. A Single Send may be sent immediately or scheduled for future delivery.\n\nSingle Sends can serve many use cases, including promotional offers, engagement campaigns, newsletters, announcements, legal notices, or policy updates.\n\nThe Single Sends API allows you to create, retrieve, update, delete, schedule, and deliver your Single Sends. There are also endpoints for searching and statistics to help you maintain and alter your Single Sends as you learn more and further develop your campaigns.\n\nThe Single Sends API changed on **May 6, 2020**. Please check the SendGrid Knowledge Center for updates and instructions here: [https://sendgrid.com/docs/for-developers/sending-email/single-sends-2020-update/](https://sendgrid.com/docs/for-developers/sending-email/single-sends-2020-update/)" - }, - { - "divider": false, - "items": [ - { - "_id": "POST_marketing-test-sendemail", - "type": "endpoints" - } - ], - "name": "Send Test Email" - }, - { - "divider": false, - "items": [ - { - "_id": "automationQueryParams", - "type": "traits" - }, - { - "_id": "singlesendQueryParams", - "type": "traits" - }, - { - "_id": "singlesendQueryParams2", - "type": "traits" - }, - { - "_id": "errorResponse", - "type": "traits" - }, - { - "_id": "baseParams", - "type": "traits" - }, - { - "_id": "pagination", - "type": "traits" - }, - { - "_id": "errors", - "type": "schemas" - }, - { - "_id": "metadata", - "type": "schemas" - }, - { - "_id": "metrics", - "type": "schemas" - }, - { - "_id": "singlesends-response", - "type": "schemas" - }, - { - "_id": "automations-response", - "type": "schemas" - }, - { - "_id": "automations-link-stats-response", - "type": "schemas" - }, - { - "_id": "singlesends-link-stats-response", - "type": "schemas" - }, - { - "_id": "link-tracking-metadata", - "type": "schemas" - }, - { - "_id": "getall-automation-stats", - "type": "endpoints" - }, - { - "_id": "get-automation-stat", - "type": "endpoints" - }, - { - "_id": "getall-singlesend-stats", - "type": "endpoints" - }, - { - "_id": "get-singlesend-stat", - "type": "endpoints" - }, - { - "_id": "get-automation-link-stat", - "type": "endpoints" - }, - { - "_id": "get-singlesend-link-stat", - "type": "endpoints" - }, - { - "_id": "get-singlesend-stats-export", - "type": "endpoints" - }, - { - "_id": "get-automations-stats-export", - "type": "endpoints" - } - ], - "name": "Marketing Campaigns Stats", - "description": "The Marketing Campaigns Stats endpoints allow you to retrieve stats for both Automations and Single Sends.\n\n**Note:** These endpoints provide stats for Marketing Campaigns only. For stats related to event tracking, please see the **Stats** section under **Event Tracking** below." - }, - { - "divider": true, - "items": [], - "name": "Legacy Marketing Campaigns" - }, - { - "name": "Sender Identities API", - "items": [ - { - "_id": "senderID", - "type": "schemas" - }, - { - "_id": "sender-id-request", - "type": "schemas" - }, - { - "_id": "POST_senders", - "type": "endpoints" - }, - { - "_id": "GET_v3-senders", - "type": "endpoints" - }, - { - "_id": "GET_v3-senders-sender_id", - "type": "endpoints" - }, - { - "_id": "PATCH_v3-senders-sender_id", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "POST_v3-senders-sender_id-resend_verification" - }, - { - "_id": "DELETE_v3-senders-sender_id", - "type": "endpoints" - } - ], - "description": "A [Sender Identity](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/) is the email address from which an email is sent. Sender Identities must be verified before use.\n\nIf your domain has been authenticated, it will auto verify on creation. Otherwise, a verification email will be sent to the `from.email`.", - "divider": false - }, - { - "items": [ - { - "type": "schemas", - "_id": "contactdb_list" - }, - { - "_id": "POST_contactdb-lists", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-lists", - "type": "endpoints" - }, - { - "_id": "DELETE_contactdb-lists", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-lists-listid", - "type": "endpoints" - }, - { - "_id": "PATCH_contactdb-lists-listid", - "type": "endpoints" - }, - { - "_id": "DELETE_contactdb-lists-listid", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-lists-listid-recipients", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "POST_contactdb-lists-listid-recipients-recipientid" - }, - { - "_id": "DELETE_contactdb-lists-listid-recipients-recipientid", - "type": "endpoints" - }, - { - "_id": "POST_contactdb-lists-listid-recipients", - "type": "endpoints" - } - ], - "name": "Contacts API - Lists", - "description": "Elements that can be shared among more than one endpoint definition.", - "divider": false - }, - { - "items": [ - { - "type": "schemas", - "_id": "contactdb_recipient_count" - }, - { - "_id": "contactdb_recipient", - "type": "schemas" - }, - { - "_id": "contactdb_recipient_response", - "type": "schemas" - }, - { - "_id": "contacts", - "type": "schemas" - }, - { - "_id": "POST_contactdb-recipients", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-status", - "type": "endpoints" - }, - { - "_id": "PATCH_contactdb-recipients", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "DELETE_contactdb-recipients" - }, - { - "_id": "GET_contactdb-recipients", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-recipients-recipientid", - "type": "endpoints" - }, - { - "_id": "DELETE_contactdb-recipients-recipientid", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-recipients-recipientid-lists", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-recipients-billablecount", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-recipients-count", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-recipients-search", - "type": "endpoints" - }, - { - "_id": "POST_contactdb-recipients-search", - "type": "endpoints" - } - ], - "name": "Contacts API - Recipients", - "description": "Elements that can be shared among more than one endpoint definition.", - "divider": false - }, - { - "items": [ - { - "_id": "contactdb_custom_field_with_id", - "type": "schemas" - }, - { - "_id": "contactdb_custom_field_with_id_value", - "type": "schemas" - }, - { - "type": "schemas", - "_id": "contactdb_custom_field" - }, - { - "_id": "POST_contactdb-customfields", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-customfields", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-customfields-customfieldid", - "type": "endpoints" - }, - { - "_id": "DELETE_contactdb-customfields-customfieldid", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-reservedfields", - "type": "endpoints" - } - ], - "description": "Elements that can be shared among more than one endpoint definition.", - "divider": false, - "name": "Contacts API - Custom Fields" - }, - { - "items": [ - { - "_id": "contactdb_segments", - "type": "schemas" - }, - { - "_id": "contactdb_segments_with_id", - "type": "schemas" - }, - { - "_id": "contactdb_segments_conditions", - "type": "schemas" - }, - { - "_id": "POST_contactdb-segments", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-segments", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-segments-segmentid", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "PATCH_contactdb-segments-segmentid" - }, - { - "_id": "DELETE_contactdb-segments-segmentid", - "type": "endpoints" - }, - { - "_id": "GET_contactdb-segments-segmentid-recipients", - "type": "endpoints" - } - ], - "name": "Contacts API - Segments", - "description": "Elements that can be shared among more than one endpoint definition.", - "divider": false - }, - { - "items": [ - { - "_id": "GET_categories", - "type": "endpoints" - }, - { - "_id": "GET_categories-stats-sums", - "type": "endpoints" - }, - { - "_id": "GET_categories-stats", - "type": "endpoints" - }, - { - "_id": "category_stats", - "type": "schemas" - } - ], - "name": "Categories", - "description": "Categories can help organize your email analytics by enabling you to “tag” emails by type or broad topic. You can define your own custom categories.\n\nYou can retrieve statistics based on your categories, but note that category statistics are only available for the previous thirteen months.", - "divider": false - }, - { - "name": "Campaigns API", - "description": "Allows you to create, manage, send, and schedule campaigns.", - "divider": false, - "items": [ - { - "_id": "campaign_request", - "type": "schemas" - }, - { - "type": "schemas", - "_id": "campaign_response" - }, - { - "_id": "POST_campaigns", - "type": "endpoints" - }, - { - "_id": "GET_campaigns", - "type": "endpoints" - }, - { - "_id": "GET_campaigns-campaignid", - "type": "endpoints" - }, - { - "_id": "DELETE_campaigns-campaignid", - "type": "endpoints" - }, - { - "_id": "PATCH_campaigns-campaignid", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "POST_campaigns-campaignid-schedules-now" - }, - { - "_id": "POST_campaigns-campaignid-schedules", - "type": "endpoints" - }, - { - "_id": "PATCH_campaigns-campaignid-schedules", - "type": "endpoints" - }, - { - "_id": "GET_campaigns-campaignid-schedules", - "type": "endpoints" - }, - { - "_id": "DELETE_campaigns-campaignid-schedules", - "type": "endpoints" - }, - { - "_id": "POST_campaigns-campaignid-schedules-test", - "type": "endpoints" - } - ] - }, - { - "divider": true, - "items": [], - "name": "Templates" - }, - { - "items": [ - { - "_id": "transactional_template", - "type": "schemas" - }, - { - "_id": "transactional-templates-template-lean", - "type": "schemas" - }, - { - "_id": "transactional-template-warning", - "type": "schemas" - }, - { - "_id": "POST_templates", - "type": "endpoints" - }, - { - "_id": "POST_templates-templateid", - "type": "endpoints" - }, - { - "_id": "GET_templates", - "type": "endpoints" - }, - { - "_id": "GET_templates-templateid", - "type": "endpoints" - }, - { - "_id": "PATCH_templates-templateid", - "type": "endpoints" - }, - { - "_id": "DELETE_templates-templateid", - "type": "endpoints" - } - ], - "name": "Transactional Templates", - "description": "An HTML template that can establish a consistent design for [transactional emails](https://sendgrid.com/use-cases/transactional-email/).\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns designs](https://sendgrid.com/docs/ui/sending-email/working-with-marketing-campaigns-email-designs/). For more information about transactional templates, please see our [Dynamic Transactional Templates documentation](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/).", - "divider": false - }, - { - "items": [ - { - "_id": "transactional-templates-version-output-lean", - "type": "schemas" - }, - { - "_id": "transactional_template_version_create", - "type": "schemas" - }, - { - "_id": "transactional_template_version_output", - "type": "schemas" - }, - { - "_id": "POST_templates-templateid-versions", - "type": "endpoints" - }, - { - "_id": "POST_templates-templateid-versions-versionid-activate", - "type": "endpoints" - }, - { - "_id": "GET_templates-templateid-versions-versionid", - "type": "endpoints" - }, - { - "_id": "PATCH_templates-templateid-versions-versionid", - "type": "endpoints" - }, - { - "_id": "DELETE_templates-templateid-versions-versionid", - "type": "endpoints" - } - ], - "name": "Transactional Templates Versions", - "description": "Represents the code for a particular transactional template. Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\nFor more information about transactional templates, please see our [Transactional Templates documentation](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/). You can also manage your Transactional Templates in the [Dynamic Templates section of the Twilio SendGrid App](https://mc.sendgrid.com/dynamic-templates).", - "divider": false - }, - { - "divider": true, - "items": [], - "name": "Event Tracking" - }, - { - "divider": false, - "items": [ - { - "_id": "webhooks-event-webhook-request", - "type": "schemas" - }, - { - "_id": "event-webhook-response", - "type": "schemas" - }, - { - "_id": "event-webhook-update-oauth-request", - "type": "schemas" - }, - { - "_id": "GET_user-webhooks-event-settings", - "type": "endpoints" - }, - { - "_id": "GET_user-webhooks-parse-settings", - "type": "endpoints" - }, - { - "_id": "GET_user-webhooks-parse-stats", - "type": "endpoints" - }, - { - "_id": "GET_user-webhooks-event-settings-signed", - "type": "endpoints" - }, - { - "_id": "POST_user-webhooks-event-test", - "type": "endpoints" - }, - { - "_id": "PATCH_user-webhooks-event-settings", - "type": "endpoints" - }, - { - "_id": "PATCH_user-webhooks-event-settings-signed", - "type": "endpoints" - } - ], - "name": "Webhooks" - }, - { - "divider": false, - "items": [ - { - "_id": "GET-messages", - "type": "endpoints" - }, - { - "_id": "GET-v3-messages-msg_id", - "type": "endpoints" - }, - { - "_id": "POST_v3-messages-download", - "type": "endpoints" - }, - { - "_id": "GET_v3-messages-download-download_uuid", - "type": "endpoints" - }, - { - "_id": "email-activity-response-common-fields", - "type": "schemas" - } - ], - "name": "Email Activity", - "description": "**You must purchase [additional email activity history](https://app.sendgrid.com/settings/billing/addons/email_activity) to gain access to the Email Activity Feed API.**\n\nThe Email Activity API allows you to query all of your stored messages, query individual messages, and download a CSV with data about the stored messages.\n\nOnce retrieved, you can inspect the data associated with your messages to better understand your mail send. For example, you may retrieve all bounced messages or all messages with the same subject line and search for commonalities among them.\n\nSee \"[Getting Started with the Email Activity Feed API](https://sendgrid.com/docs/for-developers/sending-email/getting-started-email-activity-api/)\" for help building queries and working with the API.\n\nYou can also work with email activity in the **Activity** section of the [Twilio SendGrid App](https://app.sendgrid.com/email_activity)." - }, - { - "items": [ - { - "_id": "subscription_tracking_settings", - "type": "schemas" - }, - { - "_id": "click-tracking", - "type": "schemas" - }, - { - "_id": "google_analytics_settings", - "type": "schemas" - }, - { - "_id": "GET_trackingsettings", - "type": "endpoints" - }, - { - "_id": "GET_trackingsettings-click", - "type": "endpoints" - }, - { - "_id": "PATCH_trackingsettings-click", - "type": "endpoints" - }, - { - "_id": "GET_trackingsettings-googleanalytics", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "PATCH_trackingsettings-googleanalytics" - }, - { - "_id": "GET_trackingsettings-open", - "type": "endpoints" - }, - { - "_id": "PATCH_trackingsettings-open", - "type": "endpoints" - }, - { - "_id": "GET_trackingsettings-subscription", - "type": "endpoints" - }, - { - "_id": "PATCH_trackingsettings-subscription", - "type": "endpoints" - } - ], - "name": "Settings - Tracking", - "description": "You can track many of your recipients' interactions with your emails, including:\n\n- Opening emails\n- Clicking links\n- Subscribing to (or unsubscribing from) your emails\n\nFor more information about tracking, please see our [Tracking Settings documentation](https://sendgrid.com/docs/ui/account-and-settings/tracking/).", - "divider": false - }, - { - "divider": false, - "items": [ - { - "_id": "Ag8mEYHMm5BNuLh4B", - "type": "schemas" - }, - { - "_id": "statsAdvancedStatsBaseQueryStrings", - "type": "traits" - }, - { - "_id": "statsAdvancedQueryStringsLimitOffset", - "type": "traits" - }, - { - "_id": "advanced_stats_mailbox_provider", - "type": "schemas" - }, - { - "_id": "stats-advanced-global-stats", - "type": "schemas" - }, - { - "_id": "GET_stats", - "type": "endpoints" - }, - { - "_id": "GET_geo-stats", - "type": "endpoints" - }, - { - "_id": "GET_devices-stats", - "type": "endpoints" - }, - { - "_id": "GET_clients-stats", - "type": "endpoints" - }, - { - "_id": "GET_clients-clienttype-stats", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "GET_mailboxproviders-stats" - }, - { - "_id": "GET_browsers-stats", - "type": "endpoints" - }, - { - "_id": "stats-advanced-stats-base-schema", - "type": "schemas" - }, - { - "type": "schemas", - "_id": "advanced_stats_clicks" - }, - { - "_id": "advanced_stats_opens", - "type": "schemas" - }, - { - "_id": "advanced_stats_clicks_opens", - "type": "schemas" - } - ], - "name": "Stats", - "description": "Tracking your emails is an important part of being a good sender and learning about how your users interact with your email. This includes everything from basics of clicks and opens to looking at which browsers and mailbox providers your customers use.\n\nWe have broken up statistics in specific ways so that you can get at-a-glance data, as well as allowing you to get into the details of how your email is being used.\n\n> Category statistics are available for the previous thirteen months only." - }, - { - "divider": true, - "items": [], - "name": "Suppression Management" - }, - { - "description": "An email is considered [bounced](https://sendgrid.com/docs/glossary/bounces/) when the message is undeliverable and then returned to the server that sent it. Bounced emails can be either permanent or temporary failures to deliver the message.\n\nFor more information, see our [Bounces documentation](https://sendgrid.com/docs/ui/sending-email/bounces/).\n\nYou can also manage bounced emails from the [Suppression settings menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/bounces).", - "divider": false, - "items": [ - { - "_id": "GET_suppression-bounces", - "type": "endpoints" - }, - { - "_id": "GET_suppression-bounces-email", - "type": "endpoints" - }, - { - "_id": "DELETE_suppression-bounces", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "DELETE_suppression-bounces-email" - }, - { - "type": "schemas", - "_id": "bounce_response" - } - ], - "name": "Bounces API" - }, - { - "items": [ - { - "_id": "GET_suppression-blocks", - "type": "endpoints" - }, - { - "_id": "GET_suppression-blocks-email", - "type": "endpoints" - }, - { - "_id": "DELETE_suppression-blocks", - "type": "endpoints" - }, - { - "_id": "DELETE_suppression-blocks-email", - "type": "endpoints" - }, - { - "_id": "blocks-response", - "type": "schemas" - } - ], - "name": "Blocks API", - "description": "[Blocks](https://sendgrid.com/docs/glossary/blocks/) happen when your email is rejected because of an issue with the message itself rather than an issue with the recipient's address.\n\nThere are several causes for blocked emails. For example, your mail server IP address may be blocked by an ISP, or the receiving server may flag the message content using a filter. Twilio SendGrid will not suppress future messages to blocked addresses by default. \n\nFor more information, please see our [Blocks documentation](https://sendgrid.com/docs/ui/sending-email/blocks/).\n\nYou can also see your Blocks in the [Suppressions settings menu of the Twilio SendGrid App](https://app.sendgrid.com/suppressions/blocks).", - "divider": false - }, - { - "items": [ - { - "_id": "GET_suppression-spamreports", - "type": "endpoints" - }, - { - "_id": "GET_suppression-spamreports-email", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "DELETE_suppression-spamreports" - }, - { - "_id": "DELETE_suppression-spamreports-email", - "type": "endpoints" - }, - { - "_id": "spam-reports-response", - "type": "schemas" - } - ], - "name": "Spam Reports API", - "description": "Spam Reports are triggered when a recipient marks one of your emails as spam. Spam reports can only be gathered from Internet Service Providers (ISPs) that provide a feedback loop.\n\nIt is important that addresses that have marked your messages as spam be permanently removed from your send list, even if the recipients have previously opted into receiving your messages. Continuing to send to customers who have reported your email as spam can severely affect your deliverability rating.\n\nYou can also access your Spam Reports from the [Suppressions settings menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/spam_reports).\n\nFor more information, please see our [Spam Reports documentation](https://sendgrid.com/docs/ui/analytics-and-reporting/spam-reports/).", - "divider": false - }, - { - "items": [ - { - "_id": "POST_asm-suppressions-global", - "type": "endpoints" - }, - { - "_id": "GET_suppression-unsubscribes", - "type": "endpoints" - }, - { - "_id": "GET_asm-suppressions-global-email", - "type": "endpoints" - }, - { - "_id": "DELETE_asm-suppressions-global-email", - "type": "endpoints" - }, - { - "_id": "suppressions-request", - "type": "schemas" - } - ], - "name": "Suppressions - Global Suppressions", - "description": "A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [Global Unsubscribes documentation](https://sendgrid.com/docs/ui/sending-email/global-unsubscribes/).", - "divider": false - }, - { - "divider": false, - "items": [ - { - "_id": "POST_asm-groups", - "type": "endpoints" - }, - { - "_id": "GET_asm-groups", - "type": "endpoints" - }, - { - "_id": "GET_asm-groups-groupid", - "type": "endpoints" - }, - { - "_id": "PATCH_asm-groups-groupid", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "DELETE_asm-groups-groupid" - }, - { - "_id": "suppression-group-request-base", - "type": "schemas" - }, - { - "_id": "suppression_group", - "type": "schemas" - } - ], - "name": "Suppressions - Unsubscribe Groups", - "description": "Suppression groups, or unsubscribe groups, are specific types or categories of emails from which you would like your recipients to be able to unsubscribe. For example: Daily Newsletters, Invoices, and System Alerts are all potential suppression groups. Visit the main documentation to [learn more about suppression/unsubscribe groups](https://sendgrid.com/docs/ui/sending-email/unsubscribe-groups/)\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach Twilio SendGrid account can create up to 25 different suppression groups." - }, - { - "name": "Suppressions - Suppressions", - "items": [ - { - "_id": "POST_asm-groups-groupid-suppressions", - "type": "endpoints" - }, - { - "type": "endpoints", - "_id": "POST_asm-groups-groupid-suppressions-search" - }, - { - "_id": "GET_asm-groups-groupid-suppressions", - "type": "endpoints" - }, - { - "_id": "GET_asm-suppressions", - "type": "endpoints" - }, - { - "_id": "GET_asm-suppressions-email", - "type": "endpoints" - }, - { - "_id": "DELETE_asm-groups-groupid-suppressions-email", - "type": "endpoints" - } - ], - "description": "Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/ui/sending-email/unsubscribe-groups/). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.", - "divider": false - }, - { - "items": [ - { - "_id": "GET_suppression-invalidemails", - "type": "endpoints" - }, - { - "_id": "GET_suppression-invalidemails-email", - "type": "endpoints" - }, - { - "_id": "DELETE_suppression-invalidemails", - "type": "endpoints" - }, - { - "_id": "DELETE_suppression-invalidemails-email", - "type": "endpoints" - }, - { - "_id": "invalid-email", - "type": "schemas" - } - ], - "name": "Invalid Emails API", - "description": "\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server.\n\nExamples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [Invalid Email documentation](https://sendgrid.com/docs/ui/sending-email/invalid-emails/).", - "divider": false - }, - { - "divider": true, - "items": [], - "name": "Inbound Parse" - }, - { - "items": [ - { - "_id": "parse-setting", - "type": "schemas" - }, - { - "_id": "POST_user-webhooks-parse-settings", - "type": "endpoints" - }, - { - "_id": "GET_user-webhooks-parse-settings", - "type": "endpoints" - }, - { - "_id": "GET_user-webhooks-parse-settings-hostname", - "type": "endpoints" - }, - { - "_id": "PATCH_user-webhooks-parse-settings-hostname", - "type": "endpoints" - }, - { - "_id": "DELETE_user-webhooks-parse-settings-hostname", - "type": "endpoints" - } - ], - "name": "Settings - Inbound Parse", - "divider": false, - "description": "Twilio SendGrid’s Inbound Parse Webhook allows you to receive emails as multipart/form-data at a URL of your choosing. SendGrid will grab the content, attachments, and the headers from any email it receives for your specified hostname.\n\nSee \"[Setting up the Inbound Parse Webhook](https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/)\" for help configuring the Webhook. You can also manage the Inbound Parse Webhook in the [Twilio SendGrid App](https://app.sendgrid.com/settings/parse).\n\nTo begin processing email using SendGrid's Inbound Parse Webhook, you will have to setup MX Records, choose the hostname (or receiving domain) that will be receiving the emails you want to parse, and define the URL where you want to POST your parsed emails. If you do not have access to your domain's DNS records, you must work with someone in your organization who does." - }, - { - "divider": false, - "name": "Global: Models", - "items": [ - { - "_id": "global_error_response_schema", - "type": "schemas" - }, - { - "_id": "global:id", - "type": "schemas" - }, - { - "_id": "global:empty_request", - "type": "schemas" - }, - { - "_id": "selfmetadata", - "type": "schemas" - }, - { - "_id": "error", - "type": "schemas" - }, - { - "_id": "link", - "type": "schemas" - }, - { - "_id": "metadata", - "type": "schemas" - }, - { - "_id": "webhook", - "type": "schemas" - } - ], - "description": "Elements that can be shared among more than one endpoint definition." - }, - { - "name": "Global: Traits", - "items": [ - { - "_id": "onBehalfOfSubuser", - "type": "traits" - }, - { - "_id": "globalErrors", - "type": "traits" - }, - { - "_id": "makoErrorResponse", - "type": "traits" - } - ], - "description": "Elements that can be shared among more than one endpoint definition.", - "divider": false - }, - { - "items": [ - { - "_id": "credentials", - "type": "schemas" - } - ], - "name": "Credentials", - "divider": false - } - ] - } - }, - "functions": {}, - "textSections": { - "api-responses": { - "id": "api-responses", - "name": "Responses", - "content": "## Content-Type Header\n\nAll responses are returned in JSON format. We specify this by sending the `Content-Type` header.\n\n```bash\nGET https://api.sendgrid.com/v3/resource HTTP/1.1\n```\n\n```json\nHTTP/1.1 200 OK\nContent-Type: application/json\n\n{\n \"foo\": \"bar\"\n}\n```\n\n## Status Codes\n\nBelow is a table containing descriptions of the various status codes we currently support against various resources.\n\n| **Status Code** | **Description** |\n|---|---|\n| 200 | No error |\n| 201 | Successfully created |\n| 204 | Successfully deleted |\n| 400 | Bad request|\n| 401 | Requires authentication |\n| 403 | From address doesn't match Verified Sender Identity. To learn how to resolve this error, see our [Sender Identity requirements]({{root_url}}for-developers/sending-email/sender-identity/). |\n| 406 | Missing Accept header. For example: `Accept: application/json` |\n| 429 | Too many requests/Rate limit exceeded |\n| 500 | Internal server error |\n\n\n## Pagination\n\nWhen a request is made with a pagination query, the following data is included in the header to allow for easy traversal of previous, current, first, and last page of the data set.\n\n```bash\nGET https://api.sendgrid.com/v3/resource?limit=5&offset=0 HTTP/1.1\n```\n\n```json\nHTTP/1.1 200 OK\nContent-Type: application/json\n\nLink: ; rel=\"next\"; title=\"2\",\n ; rel=\"prev\"; title=\"1\",\n ; rel=\"last\"; title=\"3\",\n ; rel=\"first\"; title=\"1\"\n\n```", - "public": true - }, - "mail-send-limitations": { - "id": "mail-send-limitations", - "name": "Limitations", - "content": "There are several rate limitations and restrictions that you should be aware of when using the v3 Mail Send endpoint.\n\n* The total size of your email, including attachments, must be less than 30MB.\n* The total number of recipients must no more than 1000. This includes all recipients defined within the `to`, `cc`, and `bcc` parameters, across each object that you include in the `personalizations` array.\n* The total length of custom arguments must be less than 10000 bytes.\n* Unicode encoding is not supported for the `from` field.\n* The `to.name`, `cc.name`, and `bcc.name` personalizations cannot include either the `;` or `,` characters.\n\nFor more specific, parameter level requirements and limitations, please refer to the [v3/mail/send documentation](https://sendgrid.api-docs.io/v3.0/mail-send/v3-mail-send).", - "public": true - }, - "mail-send-validation": { - "id": "mail-send-validation", - "name": "Validation", - "content": "Whenever you make a request to the v3 Mail Send endpoint, your JSON payload is validated before your email is sent. If there are any errors, SendGrid will attempt to identify and return as many issues as possible for each request. For more information, please read our [error documentation](https://sendgrid.api-docs.io/v3.0/mail-send/mail-send-errors).", - "public": true - }, - "api-errors": { - "id": "api-errors", - "name": "Errors", - "content": "Sometimes your API call will generate an error. Here you will find additional information about what to expect if you don’t format your request properly, or we fail to properly process your request.\n\n## Response Codes\n\n| **Status Code** | **Description** |\n|---|---|\n| 400 | Bad request|\n| 401 | Requires authentication |\n| 406 | Missing Accept header. For example: `Accept: application/json` |\n| 429 | Too many requests/Rate limit exceeded |\n| 500 | Internal server error |\n\n## Failed Requests\n\nThe general format guidelines are displayed when the accompanying status code is returned.\n\n```bash\nGET https://api.sendgrid.com/v3/resource HTTP/1.1\n```\n\n```json\nHTTP/1.1 400 BAD REQUEST\nContent-Type: application/json\n\n{\n \"errors\": [\n {\"field\": \"identifier1\", \"message\": \"error message explained\"},\n {\"field\": \"identifier2\", \"message\": \"error message explained\"},\n {\"field\": \"identifier3\", \"message\": \"error message explained\"},\n ]\n}\n```", - "public": true - }, - "api-authentication": { - "id": "api-authentication", - "name": "Authentication", - "content": "## Authorization Header\n\nTo authenticate, add an `Authorization` header to your API request that contains an [API Key](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/index.html).\n\n## API Keys\n\nSendGrid’s Web API v3 supports the use of API Keys. API Keys allow you to use another method of authentication separate from your account username and password. API Keys add an additional layer of security for your account and can be assigned [specific permissions](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) to limit which areas of your account they may be used to access. [API Keys can be generated in your account](https://app.sendgrid.com/settings/api_keys). To use keys, you must set a plain text header named “Authorization” with the contents of the header being “Bearer XXX” where XXX is your API Secret Key.\n\n### Example Header\n\n```bash\nGET https://api.sendgrid.com/v3/resource HTTP/1.1\nAuthorization: Bearer Your.API.Key-HERE\n```\n\n```bash\ncurl -X \"GET\" \"https://api.sendgrid.com/v3/templates\" -H \"Authorization: Bearer Your.API.Key-HERE\" -H \"Content-Type: application/json\"\n```", - "public": true - }, - "api-rate-limits": { - "id": "api-rate-limits", - "name": "Rate Limits", - "content": "## Rate Limit Response Header\n\nAll calls within the Web API are allotted a specific number of requests per refresh period.\n\nEach Web API request returns the following header information regarding rate limits and number of requests left.\n\nDepending on the endpoint you are trying to reach, it will have a specific number of allowed requests per refresh period. Once this threshold has been reached, we will return a status code `429` response.\n\n### Example\n\n```bash\nGET https://api.sendgrid.com/v3/resource HTTP/1.1\n```\n\n```json\nHTTP/1.1 200 OK\nContent-Type: application/json\nX-RateLimit-Limit: 500\nX-RateLimit-Remaining: 499\nX-RateLimit-Reset: 1392815263\n\n{\n \"foo\": \"bar\"\n}\n```\n\n## When You Reach a Rate Limit\n\nYou will no longer be able to make request against that endpoint for the duration of that refresh period.\n\n### Example\n\n```bash\nGET https://api.sendgrid.com/v3/resource/ HTTP/1.1\n```\n\n```json\nHTTP/1.1 429 TOO MANY REQUESTS\nContent-Type: application/json\nX-RateLimit-Limit: 150\nX-RateLimit-Remaining: 0\nX-RateLimit-Reset: 1392815263\n\n{\n \"errors\": [\n {\n \"field\": null,\n \"message\": \"too many requests\"\n },\n ]\n}\n```", - "public": true - }, - "api-requests": { - "id": "api-requests", - "name": "Requests", - "content": "## Making a Request\n\n### Host\n\nThe host for Web API v3 requests is always `https://sendgrid.com/v3/`\n\n**All requests must be made over HTTPS. The API does not support HTTP.**\n\n### Authorization Header\n\nYou must provide an authorization header as described in [Authentication]().\n\n### HTTP Verbs\n\n| **Verb** | **Description** |\n| --- | --- |\n| GET | Retrieve a resource or group of resources |\n| POST| Create a new resource |\n| PUT | Update an existing resource |\n| DELETE | Delete an existing resource |\n| OPTIONS | View allowed verbs against a specific resource |\n\n### Accept Header\n\nThe API provides JSON responses. It doesn't currently require the [accept header](http://www.soapui.org/Best-Practices/understanding-rest-headers-and-parameters.html), but might in the future. If not set, the API will use `application/json`.\n\n```bash\nGET https://api.sendgrid.com/v3/endpoint HTTP/1.1\nAccept: application/json\n```\n\n### Arrays of Data\n\nWhen you send an array of data in a `GET` request, you will include the parameter multiple times on the URL. The parameter name does not require brackets.\n\n#### Example Array in a GET request\\\n\n```bash\nGET https://api.sendgrid.com/v3/endpoint?parameter=data1¶meter=data2 HTTP/1.1\n```\n\n## Formatting Your Request\n\n### Request Body\n\nWhen submitting data to a resource via `POST` or `PUT`, you must submit your payload in JSON.\n\n```bash\nPOST https://api.sendgrid.com/v3/templates/ HTTP/1.1\nContent-Type: application/json\n```\n\n```json\n{\n \"name\": \"new template name\"\n}\n```\n\n### Pagination\n\nSome `GET` resources allow for retrieval of information in batches. We will provide the query args in the resource documentation when available to consume.\n\nWhen requesting multiple items, we will default the request limit to 500 items. You can specify a different limit but cannot exceed the default limit.\n\nResources documented will display a bolded list of available paginated parameters if available.\n\nBelow is a basic pagination example. In the resource documentation, we will only provide the bolded list of available parameters.\n\n**A [Link Header](http://tools.ietf.org/html/rfc5988) is provided in the response for batched information.**\n\n```bash\nGET https://api.sendgrid.com/v3/resource?limit=300&offset=10 HTTP/1.1\n```\n\n| **Parameter** | **Description** |\n|---|---|\n| limit | The number of records to return |\n| offset | The number of records to skip |\n\n### Search & Paramters\n\nSome resources allow for you to search by a specific field. Other resources require you to append a parameter to the URI.\n\nIn this example, we will display a paginated URI example, searching for resources where the email contains `foo`.\n\n```bash\nGET https://api.sendgrid.com/v3/resource?email=foo&bar=baz HTTP/1.1\n```\n\n## Successful Requests\n\nBelow is a general overview of what resource objects return with successful Web API requests.\n\n| **Verb** | **Resource object returned** |\n|---|---|\n| GET | Returns a single resource object or array of resource objects |\n| PATCH | Returns the updated resource object |\n| PUT | Returns the updated resource object |\n| DELETE | No content is returned |\n| POST | Returns the newly created resource object |", - "public": true - }, - "mail-send-errors": { - "id": "mail-send-errors", - "name": "Errors", - "content": "\n\n\n

Personalizations Errors

\n\n\n\n\n

personalizations

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n\n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n \n
Error CodeError MessageDetails
400
The personalization block is limited to 1000 personalizations per API request. You have provided X personalizations. Please consider splitting this into multiple requests and resending your request.
The v3 Mail Send endpoint is only capable of processing 1000 individual personalizations objects per request. If you need to send your email to more than 1000 different recipients, we recommend that you simply make more than one call. For more information about the personalizations array, and how you can use it to define who you would like you send your email to, and how you would like your email to be processed, please visit our Personalizations documentation.
You must have at least one personalization.
Every email you send must have at least one recipient email address included. Recipients are defined in the personalizations array. For more information on how to use personalizations to define who you want to send your email to, please visit our Personalizations documentation.
There is a limit of 1000 total recipients (to + cc + bcc) per request.
The combined, total number of email recipients may never exceed 1000. This includes recipients defined within the to, cc, and bcc parameters. For more information on how you may specify your recipients, please visit our Personalizations documentation.
Each \"to\" object must at least have an email address and may also contain a name. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
For every recipient that you define within a personalizations.to parameter, you must include one valid email address. You are not required to include a name.
Each unique email address in the personalizations array should only be included once. You have included [email address] more than once.
To prevent the same email from being delivered to one recipient multiple times, SendGrid will confirm that you do not duplicate an email address in your request. For more information on how you may specify your recipients, please visit our Personalizations documentation.
The to parameter is required for all personalization objects.
For every single object that you include within the personalizations array, you must include at least one to email object with a valid email address. For more information on how you may specify your recipients, please visit our Personalizations documentation.
\n\n\n\n\n

personalizations.bcc

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The bcc array, when used, must at least have an email parameter with a valid email address and it may also contain a name parameter. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
For every blind carbon copy of your email, you must include one, valid recipient email address. However, you are not required to include a corresponding name with the recipient email address. For more information on how to use personalizations to define who you want to send your email to, please visit our Personalizations documentation.
Each recipient object must at least have an email address and may also contain a name. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
Every recipient that you define within the personalizations.cc array must be in the form of an email object including one, valid email address. You are not required to include a name.
Each unique email address in the personalization block should only be included once. You have included [email address] more than once.
To prevent the same email from being delivered to one recipient multiple times, SendGrid will confirm that you do not duplicate an email address in your request. For more information on how you may specify your recipients, please visit our Personalizations documentation.
\n\n\n\n\n

personalizations.cc

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The cc array, when used, must at least have an email parameter with a valid email address and it may also contain a name parameter. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
For every carbon copy of your email, you must include one valid recipient email address. However, you are not required to include a corresponding name with the recipient email address. For more information on how to use personalizations to define who you want to send your email to, please visit our Personalizations documentation.
Each recipient object must at least have an email address and may also contain a name. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
Every recipient that you define within the personalizations.cc array must be in the form of an email object including one, valid email address. You are not required to include a name.
Each unique email address in the personalization block should only be included once. You have included [email address] more than once.
To prevent the same email from being delivered to one recipient multiple times, SendGrid will confirm that you do not duplicate an email address in your request. For more information on how you may specify your recipients, please visit our Personalizations documentation.
\n\n\n\n\n

personalizations.custom_args

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
All values of custom arguments object must be strings
Custom argument values must always be strings. You cannot define arrays, integers, or booleans as custom argument values. Click here more information about how to use custom arguments.
custom_args cannot be empty.
If you include the custom_args parameter, you must include at least one value. If you do not want to use any custom arguments, simply omit the custom_arg param from your request. Click here more information about how to use custom arguments.
The combined size of both global and personalization custom arguments may not exceed 10,000 bytes per personalization.
personalizations[x].custom_args will be merged with message level custom_args, overriding any conflicting keys. The combined total size of the resulting custom arguments, after merging, for each personalization may not exceed 10,000 bytes. Click here more information about how to use custom arguments.
\n\n\n\n\n

personalizations.headers

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
All values of the headers object must be strings.
The object type of every header that you include must be a string. You cannot include headers that are integers, booleans, or arrays.
The headers cannot contain duplicate keys.
You may not include the same header more than once.
Header keys cannot contain non-ASCII characters or empty spaces.
When defining the headers that you would like to use, you must make sure that the string contains only ASCII characters.
Header cannot be one of the reserved keys.
Some header keys are reserved. You may not include any of the following reserved keys: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC.
\n\n\n\n\n

personalizations.send_at

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The send_at parameter is expecting a Unix timestamp as an integer. We will send immediately if you include a send_at timestamp that is in the past.
send_at accepts a unix timestamp representing when you want your email to be sent from SendGrid. If you want the email to be sent at the time of your API request, simply omit the send_at parameter.
Scheduling more than 72 hours in advance is forbidden.
The send_at parameter allows you to schedule your email to be sent up to 72 hours in advance, but due to our constraints, we cannot schedule emails more than 72 hours in the future. For more information on scheduling parameters, please see our API Reference.
\n\n\n\n\n

personalizations.subject

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The subject of your email must be a string at least one character in length.
You are required to include a subject for every email you send, and you may not include an empty subject. The minimum length of your subject is one character.
The subject is required. You can get around this requirement if you use a template with a subject defined.
Every email must have a subject. This can be accomplished 3 ways: you include a template that has a subject, you define a global subject, or every single personalizations object has a subject.
\n\n\n\n\n

personalizations.substitutions

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The substitution values must be an object of key/value pairs, where the values are all strings.
Substitutions must always follow the pattern \"substitution_tag\": \"value to substitute\". The value to substitute for the \"substitution_tag\" must always be a string.
You are limited to 10,000 substitutions.
You may not make more than 10,000 bytes worth of substitutions per request. Substitutions will apply to the content of your email, in addition to the subject and reply_to parameters
\n\n\n\n\n

personalizations.to

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The to array must at least have an email parameter with a valid email address and it may also contain a name parameter. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
Every email you send must have at least one, valid recipient email address included. However, you are not required to include a corresponding name with the recipient email address. For more information on how to use personalizations to define who you want to send your email to, please visit our Personalizations documentation.
\n\n\n\n\n

ASM Errors

\n\n\n\n\n

asm.group_id

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The ASM group ID must be an integer.
Suppression Groups, or unsubscribe groups, are a great way to record which emails your recipients want to receive. Including the asm.group_id in your request allows you to group your email with other, similar sends. However, these group IDs are always generated as integers, and so you must ensure that asm.group_id is defined as an integer. For more information please read our Unsubscribe Groups documentation.
The ASM group ID must be a valid Group ID on your account. You provided [YOUR ASM GROUP ID].
\n\n\n\n\n

asm.groups_to_display

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The ASM Group IDs to display must be an array of integers.
All ASM groups to display must be valid ASM groups IDs on your account. You provided {invalid IDs}.
There is a limit of 25 unsubscribe groups that can be displayed to a user at a time.\n
\n\n\n\n\n

Attachment Errors

\n\n\n\n\n

attachments.content

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The attachment content must be base64 encoded.
The attachment content must be a string at least one character in length.
\n\n\n\n\n

attachments.content_id

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The content ID of your attachment must be a string. You provided [YOUR CONTENT ID].
The content_id is a unique id that you specify for the attachment. This is used when the disposition is set to \"inline\" and the attachment is an image, allowing the file to be displayed within the body of your email. For example, <img src=\"cid:ii_139db99fdb5c3704\"></img>
The content ID of your attachment cannot contain CRLF characters.
When defining your content_id, you may not include the characters ;, ,, n, or r.
\n\n\n\n\n

attachments.disposition

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The disposition of your attachment can be either \"inline\" or \"attachment\". You provided [YOUR DISPOSITION].
The content-disposition of your attachment defines how you would like the attachment to be displayed. For example, \"inline\" results in the attached file being displayed automatically within the message while \"attachment\" results in the attached file requiring some action to be taken before it is displayed (e.g. opening or downloading the file). attachments.disposition always defaults to \"attachment\". Can be either \"attachment\" or \"inline\".
\n\n\n\n\n

attachments.filename

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The filename of your attachment must be a string.
The filename of your attachment cannot contain CRLF characters.
When defining the filename of your attachment, you may not include the characters ;, ,, n, or r.
filename is required.
You must always include a filename for your attachment.
\n\n\n\n\n

attachments.type

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The attachment type must be a string and at least one character in length.
The type cannot contain ‘;’, or CRLF characters.
When defining the type of your attachment content, you may not include the characters ;, ,, n, or r.
\n\n\n\n\n

Batch ID Errors

\n\n\n\n\n

batch_id

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The batch_id must be a string.
Batch IDs are always generated as strings, so when you choose to include a batch ID in your send, you must make sure that batch_id is defined as a string. You must first generate a batch_id via the API; it will not be automatically generated for you. See the Create a Batch ID API reference to generate a batch_id. For more information about batch IDs, and how you can use them to group sends together, please visit our API Reference.
\n\n\n\n\n

Categories Errors

\n\n\n\n\n

categories

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
There is a limit of 10 categories for each email that is sent. You provided X categories.
For more information on how you can use categories to organize your email analytics, please visit our Categories documentation.
Categories must be an array of strings.
Every object that you include within the categories array must be a string. For more information on how you can use categories to organize your email analytics, please visit our Categories documentation.
Each category must not be longer than 255 characters. [YOUR CATEGORY] exceeds this limit
he maximum length of a category is 255 characters. For more information on how you can use categories to organize your email analytics, please visit our Categories documentation.
The categories must be a unique list, and you have included [YOUR CATEGORY] more than once.
You cannot include the same category more than once within the categories array. For more information on how you can use categories to organize your email analytics, please visit our Categories documentation.
Categories can not contain non-ASCII characters.
Each category name must only be comprised of ASCII characters. For more information on how you can use categories to organize your email analytics, please visit our Categories documentation.
\n\n\n\n\n

Content Errors

\n\n\n\n\n

content

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The content param is required unless you are using a transactional template and have defined a template_ID.
You may not send an email without the content parameter unless you are using a transactional template. This is to prevent you from sending an empty email to your recipients.
There must be at least one defined content block. We typically suggest both text/plain and text/html blocks are included, but only one block is required.
You must specify at least one content type and value for every email you send. We recommend that you include both text/plain and text/html to ensure that all of your recipients are able to read your email, but you are only required to define one type of content.
\n\n\n\n\n

content.type

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
A content type is required, this tells email clients how to display the email.
You must always specify the MIME type of content you are including in your email, and if you are including the text/plain type, it must be specified first, followed by text/html, and then any other MIME types you would like to specify.
The content value must be a string at least one character in length.
You may not send an email with no content.
Your content type must be a string with length of at least one character.
The content of your email must always be contained within a string when you make your request.
Cannot contain ‘;’, or CRLF characters.
When defining the type of your content, you may not include the characters ;, ,, n, or r.
\n\n\n\n\n

content.value

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
A content value is required, this is the content of the email you are sending.
We do not allow you to send an empty email to your recipients. You must always include a value for your content.
The content value must be a string at least one character in length.
We do not allow you to send an empty email to your recipients. Even if you include the content.value parameter, it must include at least one character.
Following RFC 1341, section 7.2, if either text/html or text/plain are to be sent in your email: text/plain needs to be first, followed by text/html, followed by any other content.
The order in which you specify the MIME types of your content must always be text/plain first, if you choose to include it, followed by text/html, and then any other MIME types you wish to include.
\n\n\n\n\n

Encoding Errors

\n\n\n\n\n

Encoding

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
415
Invalid UTF8 in request
Your payload must be encoded in UTF-8. This includes any attachments.
\n\n\n\n\n

From Address Errors

\n\n\n\n\n

from

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The from object must at least have an email parameter with a valid email address and may also contain a name parameter. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
While every from parameter must include a valid email address, you are not required to include a name.
The from object must be provided for every email send. It is an object that requires the email parameter, but may also contain a name parameter. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
You are required to provide a from address whenever you send an email through SendGrid. This is used for authentication purposes and helps to build a positive sending reputation with your recipients' ISPs. You are not required to include a name within the from parameter.
\n\n\n\n\n

Headers Errors

\n\n\n\n\n

headers

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The header values must be strings.
The object type of every header that you include must be a string. You cannot include headers that are integers, booleans, or arrays.
The headers cannot contain duplicate keys.
You may not include the same header more than once.
Header keys cannot contain non-ASCII characters and empty spaces.
When defining the headers that you would like to use, you must make sure that the string contains only ASCII characters.
Header can not be one of the reserved keys.
Some header keys are reserved. You may not include any of the following reserved headers: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC.
\n\n\n\n\n

IP Pool Errors

\n\n\n\n\n

ip_pool_name

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The name of your IP pool must be a string.
The IP Pool name must be a valid pool name for your account. You provided [YOUR IP POOL NAME].
\n\n\n\n\n

Reply To Errors

\n\n\n\n\n

reply_to

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The reply_to object, when used, must at least have an email parameter with a valid email address and it may also contain a name parameter. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
For every carbon copy of your email, you must include one, valid recipient email address. However, you are not required to include a corresponding name with the recipient email address. For more information on how to use personalizations to define who you want to send your email to, please visit our Personalizations documentation.
\n\n\n\n\n

Sections Errors

\n\n\n\n\n

sections

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The section values must be strings.
The values of your sections parameter will be substituted into the content of your email. We will only perform substitutions using strings, so please make sure that your section values are always defined as strings.
\n\n\n\n\n

Send At Errors

\n\n\n\n\n

send_at

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The send_at parameter is expecting a Unix timestamp as an integer. We will send immediately if you include a send_at timestamp that is in the past.
send_at accepts a unix timestamp representing when you want your email to be sent from SendGrid. If you want the email to be sent at the time of your API request, simply omit the send_at parameter.
Scheduling more than 72 hours in advance is forbidden.
The send_at parameter allows you to schedule your email to be sent up to 72 hours in advance, but due to our constraints, we cannot schedule emails more than 72 hours in the future. For more information on scheduling parameters, please see our API Reference.
\n\n\n\n\n

Subject Line Errors

\n\n\n\n\n

subject

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The subject of your email must be a string at least one character in length.
You are required to include a subject for every email you send, and you may not include an empty subject. The minimum length of your subject is one character.
The subject is required. You can get around this requirement if you use a template with a subject defined or if every personalization has a subject defined.
Every email must have a subject. This can be accomplished 3 ways: you include a template that has a subject, you define a global subject, or every single personalizations object has a subject.
\n\n\n\n\n

Template Errors

\n\n\n\n\n

template_id

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The template ID must be a string, you provided [YOUR TEMPLATE ID].
Template IDs are always strings.
The Template ID must be a valid template id for your account. You provided [YOUR TEMPLATE ID].
We do not allow you to send an empty email, so in the event that the only content of your email is contained within your template, we want to make sure that the included template exists, and is valid.
Must be a valid template.
We do not allow you to send an empty email, so in the event that the only content of your email is contained within your template, we want to make sure that the included template exists, and is valid.
\n\n\n\n\n

Mail Settings Errors

\n\n\n\n\n

mail_settings.bcc.email

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The bcc email recipient object must at least have an email address and may also contain a name. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
You must include a recipient object when using the bcc mail setting.
\n\n\n\n\n

mail_settings.bcc.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The bcc enable param should be a boolean value.
\n\n\n\n\n

mail_settings.bypass_list_management.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The bypass list management enable param should be a boolean value.
\n\n\n\n\n

mail_settings.footer.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The footer enable param should be a boolean value.
\n\n\n\n\n

mail_settings.footer.html

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The text/html version of your footer should be a string.
\n\n\n\n\n

mail_settings.footer.text

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The text/plain version of your footer should be a string.
\n\n\n\n\n

mail_settings.sandbox_mode.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The sandbox mode enable param should be a boolean value.
\n\n\n\n\n

mail_settings.spam_check.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The spam check enable param should be a boolean value.
\n\n\n\n\n

mail_settings.spam_check.post_to_url

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The spam check url must be a string.
You must include the url to post to when using the spam check mail setting.
The `post_to_url` parameter must start with `http://` or `https://`.
\n\n\n\n\n

mail_settings.spam_check.threshold

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The spam check threshold is between 1 and 10, with the lower numbers being the most strict filtering.
You must include the spam check threshold when using the spam check mail setting.
\n\n\n\n\n

Tracking Settings Errors

\n\n\n\n\n

tracking_settings.click_tracking.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The click tracking enable param should be a boolean value.
\n\n\n\n\n

tracking_settings.click_tracking.enable_text

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The click tracking enable text must be a boolean value.
\n\n\n\n\n

tracking_settings.ganalytics.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The Google Analytics enable param must be a boolean value.
\n\n\n\n\n

tracking_settings.ganalytics.utm_campaign

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The Google Analytics utm_campaign must be a string value.
\n\n\n\n\n

tracking_settings.ganalytics.utm_content

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The Google Analytics utm_content must be a string value.
\n\n\n\n\n

tracking_settings.ganalytics.utm_medium

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The Google Analytics utm_medium must be a string value.
\n\n\n\n\n

tracking_settings.ganalytics.utm_source

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The Google Analytics utm_source must be a string value.
\n\n\n\n\n

tracking_settings.ganalytics.utm_term

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The Google Analytics utm_term must be a string value.
\n\n\n\n\n

tracking_settings.open_tracking.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The open tracking enable param should be a boolean value.
\n\n\n\n\n

tracking_settings.open_tracking.substitution_tag

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The open tracking substitution tag must be a string.
\n\n\n\n\n

tracking_settings.subscription_tracking.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The subscription tracking enable param should be a boolean value.
\n\n\n\n\n

tracking_settings.subscription_tracking.html

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The subscription tracking unsubscribe content for text/html messages must be a string.
\n\n\n\n\n

tracking_settings.subscription_tracking.substitution_tag

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The subscription tracking substitution tag must be a string value.
\n\n\n\n\n

tracking_settings.subscription_tracking.text

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The subscription tracking unsubscribe content for text/plain messages must be a string.
\n\n\n\n\n\n ", - "public": true - }, - "api-key-permissions": { - "id": "api-key-permissions", - "name": "API Key Permissions", - "content": "API Keys can be used to authenticate the use of [SendGrid’s v3 API](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access.\n\nThe following is a complete list of all possible permissions that you may assign to an API Key.\n\n* [Admin API Key Permissions](#Admin-API-Key-Permissions)\n* [Alerts](#Alerts)\n* [API Keys](#API-Keys)\n* [ASM Groups](#ASM-Groups)\n* [Billing](#Billing)\n* [Categories](#Categories)\n* [Clients](#Clients)\n* [Credentials](#Credentials)\n* [IPs](#IPs)\n* [Mail Settings](#Mail-Settings)\n* [Mail](#Mail)\n* [Marketing Campaigns](#Marketing-Campaigns)\n* [Partner Settings](#Partner-Settings)\n* [Scheduled Sends](#Scheduled-Sends)\n* [Stats](#Stats)\n* [Subusers](#Subusers)\n* [Suppressions](#Suppressions)\n* [Teammates](#Teammates)\n* [Templates](#Templates)\n* [Tracking](#Tracking)\n* [User Settings](#User-Settings)\n* [Webhook](#Webhook)\n* [Domain Authentication](#Domain-Authentication)\n* [Reverse DNS](#Reverse-DNS)\n\n\n

\n Admin API Key Permissions\n

\n\nBelow is a complete list of every API Key permission that should be given to an admin level API Key.\n\n```json\n\"scopes\": [\n \"access_settings.activity.read\",\n \"access_settings.whitelist.create\",\n \"access_settings.whitelist.delete\",\n \"access_settings.whitelist.read\",\n \"access_settings.whitelist.update\",\n \"alerts.create\",\n \"alerts.delete\",\n \"alerts.read\",\n \"alerts.update\",\n \"api_keys.create\",\n \"api_keys.delete\",\n \"api_keys.read\",\n \"api_keys.update\",\n \"asm.groups.create\",\n \"asm.groups.delete\",\n \"asm.groups.read\",\n \"asm.groups.update\",\n \"billing.create\",\n \"billing.delete\",\n \"billing.read\",\n \"billing.update\",\n \"browsers.stats.read\",\n \"categories.create\",\n \"categories.delete\",\n \"categories.read\",\n \"categories.stats.read\",\n \"categories.stats.sums.read\",\n \"categories.update\",\n \"clients.desktop.stats.read\",\n \"clients.phone.stats.read\",\n \"clients.stats.read\",\n \"clients.tablet.stats.read\",\n \"clients.webmail.stats.read\",\n \"credentials.create\",\n \"credentials.delete\",\n \"credentials.read\",\n \"credentials.update\",\n \"devices.stats.read\",\n \"email_activity.read\",\n \"geo.stats.read\",\n \"ips.assigned.read\",\n \"ips.pools.create\",\n \"ips.pools.delete\",\n \"ips.pools.ips.create\",\n \"ips.pools.ips.delete\",\n \"ips.pools.ips.read\",\n \"ips.pools.ips.update\",\n \"ips.pools.read\",\n \"ips.pools.update\",\n \"ips.read\",\n \"ips.warmup.create\",\n \"ips.warmup.delete\",\n \"ips.warmup.read\",\n \"ips.warmup.update\",\n \"mail_settings.address_whitelist.read\",\n \"mail_settings.address_whitelist.update\",\n \"mail_settings.bcc.read\",\n \"mail_settings.bcc.update\",\n \"mail_settings.bounce_purge.read\",\n \"mail_settings.bounce_purge.update\",\n \"mail_settings.footer.read\",\n \"mail_settings.footer.update\",\n \"mail_settings.forward_bounce.read\",\n \"mail_settings.forward_bounce.update\",\n \"mail_settings.forward_spam.read\",\n \"mail_settings.forward_spam.update\",\n \"mail_settings.plain_content.read\",\n \"mail_settings.plain_content.update\",\n \"mail_settings.read\",\n \"mail_settings.spam_check.read\",\n \"mail_settings.spam_check.update\",\n \"mail_settings.template.read\",\n \"mail_settings.template.update\",\n \"mail.batch.create\",\n \"mail.batch.delete\",\n \"mail.batch.read\",\n \"mail.batch.update\",\n \"mail.send\",\n \"mailbox_providers.stats.read\",\n \"marketing_campaigns.create\",\n \"marketing_campaigns.delete\",\n \"marketing_campaigns.read\",\n \"marketing_campaigns.update\",\n \"newsletter.create\",\n \"newsletter.delete\",\n \"newsletter.read\",\n \"newsletter.update\",\n \"partner_settings.new_relic.read\",\n \"partner_settings.new_relic.update\",\n \"partner_settings.read\",\n \"partner_settings.sendwithus.read\",\n \"partner_settings.sendwithus.update\",\n \"stats.global.read\",\n \"stats.read\",\n \"subusers.create\",\n \"subusers.credits.create\",\n \"subusers.credits.delete\",\n \"subusers.credits.read\",\n \"subusers.credits.remaining.create\",\n \"subusers.credits.remaining.delete\",\n \"subusers.credits.remaining.read\",\n \"subusers.credits.remaining.update\",\n \"subusers.credits.update\",\n \"subusers.delete\",\n \"subusers.monitor.create\",\n \"subusers.monitor.delete\",\n \"subusers.monitor.read\",\n \"subusers.monitor.update\",\n \"subusers.read\",\n \"subusers.reputations.read\",\n \"subusers.stats.monthly.read\",\n \"subusers.stats.read\",\n \"subusers.stats.sums.read\",\n \"subusers.summary.read\",\n \"subusers.update\",\n \"suppression.blocks.create\",\n \"suppression.blocks.delete\",\n \"suppression.blocks.read\",\n \"suppression.blocks.update\",\n \"suppression.bounces.create\",\n \"suppression.bounces.delete\",\n \"suppression.bounces.read\",\n \"suppression.bounces.update\",\n \"suppression.create\",\n \"suppression.delete\",\n \"suppression.invalid_emails.create\",\n \"suppression.invalid_emails.delete\",\n \"suppression.invalid_emails.read\",\n \"suppression.invalid_emails.update\",\n \"suppression.read\",\n \"suppression.spam_reports.create\",\n \"suppression.spam_reports.delete\",\n \"suppression.spam_reports.read\",\n \"suppression.spam_reports.update\",\n \"suppression.unsubscribes.create\",\n \"suppression.unsubscribes.delete\",\n \"suppression.unsubscribes.read\",\n \"suppression.unsubscribes.update\",\n \"suppression.update\",\n \"templates.create\",\n \"templates.delete\",\n \"templates.read\",\n \"templates.update\",\n \"templates.versions.activate.create\",\n \"templates.versions.activate.delete\",\n \"templates.versions.activate.read\",\n \"templates.versions.activate.update\",\n \"templates.versions.create\",\n \"templates.versions.delete\",\n \"templates.versions.read\",\n \"templates.versions.update\",\n \"tracking_settings.click.read\",\n \"tracking_settings.click.update\",\n \"tracking_settings.google_analytics.read\",\n \"tracking_settings.google_analytics.update\",\n \"tracking_settings.open.read\",\n \"tracking_settings.open.update\",\n \"tracking_settings.read\",\n \"tracking_settings.subscription.read\",\n \"tracking_settings.subscription.update\",\n \"user.account.read\",\n \"user.credits.read\",\n \"user.email.create\",\n \"user.email.delete\",\n \"user.email.read\",\n \"user.email.update\",\n \"user.multifactor_authentication.create\",\n \"user.multifactor_authentication.delete\",\n \"user.multifactor_authentication.read\",\n \"user.multifactor_authentication.update\",\n \"user.password.read\",\n \"user.password.update\",\n \"user.profile.read\",\n \"user.profile.update\",\n \"user.scheduled_sends.create\",\n \"user.scheduled_sends.delete\",\n \"user.scheduled_sends.read\",\n \"user.scheduled_sends.update\",\n \"user.settings.enforced_tls.read\",\n \"user.settings.enforced_tls.update\",\n \"user.timezone.read\",\n \"user.username.read\",\n \"user.username.update\",\n \"user.webhooks.event.settings.read\",\n \"user.webhooks.event.settings.update\",\n \"user.webhooks.event.test.create\",\n \"user.webhooks.event.test.read\",\n \"user.webhooks.event.test.update\",\n \"user.webhooks.parse.settings.create\",\n \"user.webhooks.parse.settings.delete\",\n \"user.webhooks.parse.settings.read\",\n \"user.webhooks.parse.settings.update\",\n \"user.webhooks.parse.stats.read\",\n \"whitelabel.create\",\n \"whitelabel.delete\",\n \"whitelabel.read\",\n \"whitelabel.update\"\n]\n```\n\n\n

\n Alerts\n

\n\n```json\n\"scopes\": [\n \"alerts.create\",\n \"alerts.delete\",\n \"alerts.read\",\n \"alerts.update\"\n]\n```\n\n\n

\n API Keys\n

\n\n```json\n\"scopes\": [\n \"api_keys.create\",\n \"api_keys.delete\",\n \"api_keys.read\",\n \"api_keys.update\"\n]\n```\n\n

\n ASM Groups\n

\n\n```json\n\"scopes\": [\n \"asm.groups.create\",\n \"asm.groups.delete\",\n \"asm.groups.read\",\n \"asm.groups.update\"\n]\n```\na>\n

\n Billing\n

\n\n**Billing permissions are mutually exclusive from all other permissions. An API Key can have *either* Billing Permissions *or* any other set of Permissions but not *both*.**\n\n```json\n\"scopes\": [\n \"billing.create\",\n \"billing.delete\",\n \"billing.read\",\n \"billing.update\"\n]\n```\n\n\n

\n Categories\n

\n\n```json\n\"scopes\": [\n \"categories.create\",\n \"categories.delete\",\n \"categories.read\",\n \"categories.update\",\n \"categories.stats.read\",\n \"categories.stats.sums.read\"\n]\n```\n\n\n

\n Clients\n

\n\n```json\n\"scopes\": [\n \"clients.desktop.stats.read\",\n \"clients.phone.stats.read\",\n \"clients.stats.read\",\n \"clients.tablet.stats.read\",\n \"clients.webmail.stats.read\"\n]\n```\n\n\n

\n Credentials\n

\n\n```json\n\"scopes\": [\n \"credentials.create\",\n \"credentials.delete\",\n \"credentials.read\",\n \"credentials.update\"\n]\n```\n\n\n

\n IPs\n

\n\n```json\n\"scopes\": [\n \"ips.assigned.read\",\n \"ips.read\",\n \"ips.pools.create\",\n \"ips.pools.delete\",\n \"ips.pools.read\",\n \"ips.pools.update\",\n \"ips.pools.ips.create\",\n \"ips.pools.ips.delete\",\n \"ips.pools.ips.read\",\n \"ips.pools.ips.update\",\n \"ips.warmup.create\",\n \"ips.warmup.delete\",\n \"ips.warmup.read\",\n \"ips.warmup.update\"\n]\n```\n\n\n

\n Mail Settings\n

\n\n```json\n\"scopes\": [\n \"mail_settings.address_whitelist.read\",\n \"mail_settings.address_whitelist.update\",\n \"mail_settings.bcc.read\",\n \"mail_settings.bcc.update\",\n \"mail_settings.bounce_purge.read\",\n \"mail_settings.bounce_purge.update\",\n \"mail_settings.footer.read\",\n \"mail_settings.footer.update\",\n \"mail_settings.forward_bounce.read\",\n \"mail_settings.forward_bounce.update\",\n \"mail_settings.forward_spam.read\",\n \"mail_settings.forward_spam.update\",\n \"mail_settings.plain_content.read\",\n \"mail_settings.plain_content.update\",\n \"mail_settings.read\",\n \"mail_settings.spam_check.read\",\n \"mail_settings.spam_check.update\",\n \"mail_settings.template.read\",\n \"mail_settings.template.update\"\n]\n```\n\n\n

\n Mail\n

\n\n```json\n\"scopes\": [\n \"mail.batch.create\",\n \"mail.batch.delete\",\n \"mail.batch.read\",\n \"mail.batch.update\",\n \"mail.send\"\n]\n```\n\n\n

\n Marketing Campaigns\n

\n\n```json\n\"scopes\": [\n \"marketing_campaigns.create\",\n \"marketing_campaigns.delete\",\n \"marketing_campaigns.read\",\n \"marketing_campaigns.update\"\n]\n```\n\n\n

\n Newsletter\n

\n\n```json\n\"scopes\": [\n \"newsletter.create\",\n \"newsletter.delete\",\n \"newsletter.read\",\n \"newsletter.update\"\n]\n```\n\n\n

\n Partner-Settings\n

\n\n```json\n\"scopes\": [\n \"partner_settings.new_relic.read\",\n \"partner_settings.new_relic.update\",\n \"partner_settings.read\",\n \"partner_settings.sendwithus.read\",\n \"partner_settings.sendwithus.update\"\n]\n```\n\na>\n

\n Scheduled Sends\n

\n\n```json\n\"scopes\": [\n \"user.scheduled_sends.create\",\n \"user.scheduled_sends.delete\",\n \"user.scheduled_sends.read\",\n \"user.scheduled_sends.update\"\n]\n```\n\n\n

\n Stats\n

\n\n```json\n\"scopes\": [\n \"email_activity.read\",\n \"stats.read\",\n \"stats.global.read\",\n \"browsers.stats.read\",\n \"devices.stats.read\",\n \"geo.stats.read\",\n \"mailbox_providers.stats.read\",\n \"clients.desktop.stats.read\",\n \"clients.phone.stats.read\",\n \"clients.stats.read\",\n \"clients.tablet.stats.read\",\n \"clients.webmail.stats.read\"\n]\n```\n\n\n

\n Subusers\n

\n\n```json\n\"scopes\": [\n \"subusers.create\",\n \"subusers.delete\",\n \"subusers.read\",\n \"subusers.update\",\n \"subusers.credits.create\",\n \"subusers.credits.delete\",\n \"subusers.credits.read\",\n \"subusers.credits.update\",\n \"subusers.credits.remaining.create\",\n \"subusers.credits.remaining.delete\",\n \"subusers.credits.remaining.read\",\n \"subusers.credits.remaining.update\",\n \"subusers.monitor.create\",\n \"subusers.monitor.delete\",\n \"subusers.monitor.read\",\n \"subusers.monitor.update\",\n \"subusers.reputations.read\",\n \"subusers.stats.read\",\n \"subusers.stats.monthly.read\",\n \"subusers.stats.sums.read\"\n \"subusers.summary.read\"\n]\n```\n\n\n

\n Suppressions\n

\n\n```json\n\"scopes\": [\n \"suppression.create\",\n \"suppression.delete\",\n \"suppression.read\",\n \"suppression.update\",\n \"suppression.bounces.create\",\n \"suppression.bounces.read\",\n \"suppression.bounces.update\",\n \"suppression.bounces.delete\",\n \"suppression.blocks.create\",\n \"suppression.blocks.read\",\n \"suppression.blocks.update\",\n \"suppression.blocks.delete\",\n \"suppression.invalid_emails.create\",\n \"suppression.invalid_emails.read\",\n \"suppression.invalid_emails.update\",\n \"suppression.invalid_emails.delete\",\n \"suppression.spam_reports.create\",\n \"suppression.spam_reports.read\",\n \"suppression.spam_reports.update\",\n \"suppression.spam_reports.delete\",\n \"suppression.unsubscribes.create\",\n \"suppression.unsubscribes.read\",\n \"suppression.unsubscribes.update\",\n \"suppression.unsubscribes.delete\"\n]\n```\n\n\n

\n Teammates\n

\n\n```json\n\"scopes\": [\n \"teammates.create\",\n \"teammates.read\",\n \"teammates.update\",\n \"teammates.delete\"\n]\n```\n\n\n

\n Templates\n

\n\n```json\n\"scopes\": [\n \"templates.create\",\n \"templates.delete\",\n \"templates.read\",\n \"templates.update\",\n \"templates.versions.activate.create\",\n \"templates.versions.activate.delete\",\n \"templates.versions.activate.read\",\n \"templates.versions.activate.update\",\n \"templates.versions.create\",\n \"templates.versions.delete\",\n \"templates.versions.read\",\n \"templates.versions.update\"\n]\n```\n\n\n

\n Tracking\n

\n\n```json\n\"scopes\": [\n \"tracking_settings.click.read\",\n \"tracking_settings.click.update\",\n \"tracking_settings.google_analytics.read\",\n \"tracking_settings.google_analytics.update\",\n \"tracking_settings.open.read\",\n \"tracking_settings.open.update\",\n \"tracking_settings.read\",\n \"tracking_settings.subscription.read\",\n \"tracking_settings.subscription.update\"\n]\n```\n\n\n

\n User Settings\n

\n\n```json\n\"scopes\": [\n \"user.account.read\",\n \"user.credits.read\",\n \"user.email.create\",\n \"user.email.delete\",\n \"user.email.read\",\n \"user.email.update\",\n \"user.multifactor_authentication.create\",\n \"user.multifactor_authentication.delete\",\n \"user.multifactor_authentication.read\",\n \"user.multifactor_authentication.update\",\n \"user.password.read\",\n \"user.password.update\",\n \"user.profile.read\",\n \"user.profile.update\",\n \"user.settings.enforced_tls.read\",\n \"user.settings.enforced_tls.update\",\n \"user.timezone.read\",\n \"user.timezone.update\",\n \"user.username.read\",\n \"user.username.update\"\n]\n```\n\n\n

\n Webhook\n

\n\n```json\n\"scopes\": [\n \"user.webhooks.event.settings.read\",\n \"user.webhooks.event.settings.update\",\n \"user.webhooks.event.test.create\",\n \"user.webhooks.event.test.read\",\n \"user.webhooks.event.test.update\",\n \"user.webhooks.parse.settings.create\",\n \"user.webhooks.parse.settings.delete\",\n \"user.webhooks.parse.settings.read\",\n \"user.webhooks.parse.settings.update\",\n \"user.webhooks.parse.stats.read\"\n]\n```\n\n\n

\n Domain Authentication (formerly Whitelabel)\n

\n\n```json\n\"scopes\": [\n \"whitelabel.create\",\n \"whitelabel.delete\",\n \"whitelabel.read\",\n \"whitelabel.update\"\n]\n```\n\n\n

\n Reverse DNS (formerly Whitelist)\n

\n\n```json\n\"scopes\": [\n \"access_settings.activity.read\",\n \"access_settings.whitelist.create\",\n \"access_settings.whitelist.delete\",\n \"access_settings.whitelist.read\",\n \"access_settings.whitelist.update\"\n]\n```", - "public": true - }, - "api-authorization": { - "id": "api-authorization", - "name": "Authorization", - "content": "# API Key Permissions List\n\nAPI Keys can be used to authenticate the use of SendGrid’s v3 Web API, or the [Mail API endpoint](https://sendgrid.com/docs/api-reference/). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissions, please visit our [API Keys docs](https://sendgrid.com/docs/ui/account-and-settings/api-keys/). \n\nThe following is a complete list of all possible permissions that you may assign to an API Key.\n\n>When updating a key to include `user` or `subuser` scopes, use basic authenitcation.\n\n## Table of Contents\n\n\n\n\n\n\n\n\n\n\n
AlertsMail SettingsTeammates
API KeysMailTemplates
ASM GroupsMarketing CampaignsSuppressions
BillingPartner SettingsTracking
CategoriesScheduled SendsUser Settings
StatsWebhookIPs
SubusersDomain AuthenticationReverse DNS
Admin API Key Scopes
\n\n\n

Alerts

\n\n```json\n\"scopes\": [\n \"alerts.create\",\n \"alerts.delete\",\n \"alerts.read\",\n \"alerts.update\"\n]\n```\n\n

API Keys

\n\n```json\n\"scopes\": [\n \"api_keys.create\",\n \"api_keys.delete\",\n \"api_keys.read\",\n \"api_keys.update\"\n]\n```\n\n

ASM Groups

\n\n```json\n\"scopes\": [\n \"asm.groups.create\",\n \"asm.groups.delete\",\n \"asm.groups.read\",\n \"asm.groups.update\"\n]\n```\n\n\n

Billing

\n\n```json\n\"scopes\": [\n \"billing.create\",\n \"billing.delete\",\n \"billing.read\",\n \"billing.update\"\n]\n```\n\n\n**Billing permissions are mutually exclusive from all other permissions. An API Key can have *either* Billing Permissions *or* any other set of Permissions but not *both*.**\n\n\n

Categories

\n\n```json\n\"scopes\": [\n \"categories.create\",\n \"categories.delete\",\n \"categories.read\",\n \"categories.update\",\n \"categories.stats.read\",\n \"categories.stats.sums.read\"\n]\n```\n\n

Stats

\n\n```json\n\"scopes\": [\n \"email_activity.read\",\n \"stats.read\",\n \"stats.global.read\",\n \"browsers.stats.read\",\n \"devices.stats.read\",\n \"geo.stats.read\",\n \"mailbox_providers.stats.read\",\n \"clients.desktop.stats.read\",\n \"clients.phone.stats.read\",\n \"clients.stats.read\",\n \"clients.tablet.stats.read\",\n \"clients.webmail.stats.read\"\n]\n```\n\n

IPs

\n\n```json\n\"scopes\": [\n \"ips.assigned.read\",\n \"ips.read\",\n \"ips.pools.create\",\n \"ips.pools.delete\",\n \"ips.pools.read\",\n \"ips.pools.update\",\n \"ips.pools.ips.create\",\n \"ips.pools.ips.delete\",\n \"ips.pools.ips.read\",\n \"ips.pools.ips.update\",\n \"ips.warmup.create\",\n \"ips.warmup.delete\",\n \"ips.warmup.read\",\n \"ips.warmup.update\"\n]\n```\n\n

Mail Settings

\n\n```json\n\"scopes\": [\n \"mail_settings.address_whitelist.read\",\n \"mail_settings.address_whitelist.update\",\n \"mail_settings.bounce_purge.read\",\n \"mail_settings.bounce_purge.update\",\n \"mail_settings.footer.read\",\n \"mail_settings.footer.update\",\n \"mail_settings.forward_bounce.read\",\n \"mail_settings.forward_bounce.update\",\n \"mail_settings.forward_spam.read\",\n \"mail_settings.forward_spam.update\",\n \"mail_settings.template.read\",\n \"mail_settings.template.update\"\n]\n```\n\n

Mail

\n\n```json\n\"scopes\": [\n \"mail.batch.create\",\n \"mail.batch.delete\",\n \"mail.batch.read\",\n \"mail.batch.update\",\n \"mail.send\"\n]\n```\n\n

Marketing Campaigns

\n\n```json\n\"scopes\": [\n \"marketing_campaigns.create\",\n \"marketing_campaigns.delete\",\n \"marketing_campaigns.read\",\n \"marketing_campaigns.update\"\n]\n```\n\n\n

Partner Settings

\n\n```json\n\"scopes\": [\n \"partner_settings.new_relic.read\",\n \"partner_settings.new_relic.update\",\n \"partner_settings.read\"\n]\n```\n\n

Scheduled Sends

\n\n```json\n\"scopes\": [\n \"user.scheduled_sends.create\",\n \"user.scheduled_sends.delete\",\n \"user.scheduled_sends.read\",\n \"user.scheduled_sends.update\"\n]\n```\n\n

Subusers

\n\n```json\n\"scopes\": [\n \"subusers.create\",\n \"subusers.delete\",\n \"subusers.read\",\n \"subusers.update\",\n \"subusers.credits.create\",\n \"subusers.credits.delete\",\n \"subusers.credits.read\",\n \"subusers.credits.update\",\n \"subusers.credits.remaining.create\",\n \"subusers.credits.remaining.delete\",\n \"subusers.credits.remaining.read\",\n \"subusers.credits.remaining.update\",\n \"subusers.monitor.create\",\n \"subusers.monitor.delete\",\n \"subusers.monitor.read\",\n \"subusers.monitor.update\",\n \"subusers.reputations.read\",\n \"subusers.stats.read\",\n \"subusers.stats.monthly.read\",\n \"subusers.stats.sums.read\"\n \"subusers.summary.read\"\n]\n```\n\n

Suppressions

\n\n```json\n\"scopes\": [\n \"suppression.create\",\n \"suppression.delete\",\n \"suppression.read\",\n \"suppression.update\",\n \"suppression.bounces.create\",\n \"suppression.bounces.read\",\n \"suppression.bounces.update\",\n \"suppression.bounces.delete\",\n \"suppression.blocks.create\",\n \"suppression.blocks.read\",\n \"suppression.blocks.update\",\n \"suppression.blocks.delete\",\n \"suppression.invalid_emails.create\",\n \"suppression.invalid_emails.read\",\n \"suppression.invalid_emails.update\",\n \"suppression.invalid_emails.delete\",\n \"suppression.spam_reports.create\",\n \"suppression.spam_reports.read\",\n \"suppression.spam_reports.update\",\n \"suppression.spam_reports.delete\",\n \"suppression.unsubscribes.create\",\n \"suppression.unsubscribes.read\",\n \"suppression.unsubscribes.update\",\n \"suppression.unsubscribes.delete\"\n]\n```\n\n

Teammates

\n\n```json\n\"scopes\": [\n \"teammates.create\",\n \"teammates.read\",\n \"teammates.update\",\n \"teammates.delete\"\n]\n```\n\n

Templates

\n\n```json\n\"scopes\": [\n \"templates.create\",\n \"templates.delete\",\n \"templates.read\",\n \"templates.update\",\n \"templates.versions.activate.create\",\n \"templates.versions.activate.delete\",\n \"templates.versions.activate.read\",\n \"templates.versions.activate.update\",\n \"templates.versions.create\",\n \"templates.versions.delete\",\n \"templates.versions.read\",\n \"templates.versions.update\"\n]\n```\n\n

Tracking

\n\n```json\n\"scopes\": [\n \"tracking_settings.click.read\",\n \"tracking_settings.click.update\",\n \"tracking_settings.google_analytics.read\",\n \"tracking_settings.google_analytics.update\",\n \"tracking_settings.open.read\",\n \"tracking_settings.open.update\",\n \"tracking_settings.read\",\n \"tracking_settings.subscription.read\",\n \"tracking_settings.subscription.update\"\n]\n```\n\n

User Settings

\n\n```json\n\"scopes\": [\n \"user.account.read\",\n \"user.credits.read\",\n \"user.email.create\",\n \"user.email.delete\",\n \"user.email.read\",\n \"user.email.update\",\n \"user.multifactor_authentication.create\",\n \"user.multifactor_authentication.delete\",\n \"user.multifactor_authentication.read\",\n \"user.multifactor_authentication.update\",\n \"user.password.read\",\n \"user.password.update\",\n \"user.profile.read\",\n \"user.profile.update\",\n \"user.settings.enforced_tls.read\",\n \"user.settings.enforced_tls.update\",\n \"user.timezone.read\",\n \"user.timezone.update\",\n \"user.username.read\",\n \"user.username.update\"\n]\n```\n\n

Webhook

\n\n```json\n\"scopes\": [\n \"user.webhooks.event.settings.read\",\n \"user.webhooks.event.settings.update\",\n \"user.webhooks.event.test.create\",\n \"user.webhooks.event.test.read\",\n \"user.webhooks.event.test.update\",\n \"user.webhooks.parse.settings.create\",\n \"user.webhooks.parse.settings.delete\",\n \"user.webhooks.parse.settings.read\",\n \"user.webhooks.parse.settings.update\",\n \"user.webhooks.parse.stats.read\"\n]\n```\n\n

Domain Authentication (formerly Whitelabel)

\n\n```json\n\"scopes\": [\n \"whitelabel.create\",\n \"whitelabel.delete\",\n \"whitelabel.read\",\n \"whitelabel.update\"\n]\n```\n\n

Reverse DNS (formerly Whitelist)

\n\n```json\n\"scopes\": [\n \"access_settings.activity.read\",\n \"access_settings.whitelist.create\",\n \"access_settings.whitelist.delete\",\n \"access_settings.whitelist.read\",\n \"access_settings.whitelist.update\"\n]\n```\n\n

Admin API Key Scopes

\n\nBelow is a complete list of every API Key scope to be given to an admin level API Key.\n\n```json\n\"scopes\": [\n \"access_settings.activity.read\",\n \"access_settings.whitelist.create\",\n \"access_settings.whitelist.delete\",\n \"access_settings.whitelist.read\",\n \"access_settings.whitelist.update\",\n \"alerts.create\",\n \"alerts.delete\",\n \"alerts.read\",\n \"alerts.update\",\n \"api_keys.create\",\n \"api_keys.delete\",\n \"api_keys.read\",\n \"api_keys.update\",\n \"asm.groups.create\",\n \"asm.groups.delete\",\n \"asm.groups.read\",\n \"asm.groups.update\",\n \"billing.create\",\n \"billing.delete\",\n \"billing.read\",\n \"billing.update\",\n \"browsers.stats.read\",\n \"categories.create\",\n \"categories.delete\",\n \"categories.read\",\n \"categories.stats.read\",\n \"categories.stats.sums.read\",\n \"categories.update\",\n \"clients.desktop.stats.read\",\n \"clients.phone.stats.read\",\n \"clients.stats.read\",\n \"clients.tablet.stats.read\",\n \"clients.webmail.stats.read\",\n \"devices.stats.read\",\n \"email_activity.read\",\n \"geo.stats.read\",\n \"ips.assigned.read\",\n \"ips.pools.create\",\n \"ips.pools.delete\",\n \"ips.pools.ips.create\",\n \"ips.pools.ips.delete\",\n \"ips.pools.ips.read\",\n \"ips.pools.ips.update\",\n \"ips.pools.read\",\n \"ips.pools.update\",\n \"ips.read\",\n \"ips.warmup.create\",\n \"ips.warmup.delete\",\n \"ips.warmup.read\",\n \"ips.warmup.update\",\n \"mail_settings.address_whitelist.read\",\n \"mail_settings.address_whitelist.update\",\n \"mail_settings.bounce_purge.read\",\n \"mail_settings.bounce_purge.update\",\n \"mail_settings.footer.read\",\n \"mail_settings.footer.update\",\n \"mail_settings.forward_bounce.read\",\n \"mail_settings.forward_bounce.update\",\n \"mail_settings.forward_spam.read\",\n \"mail_settings.forward_spam.update\",\n \"mail_settings.plain_content.read\",\n \"mail_settings.plain_content.update\",\n \"mail_settings.read\",,\n \"mail_settings.template.read\",\n \"mail_settings.template.update\",\n \"mail.batch.create\",\n \"mail.batch.delete\",\n \"mail.batch.read\",\n \"mail.batch.update\",\n \"mail.send\",\n \"mailbox_providers.stats.read\",\n \"marketing_campaigns.create\",\n \"marketing_campaigns.delete\",\n \"marketing_campaigns.read\",\n \"marketing_campaigns.update\",\n \"partner_settings.new_relic.read\",\n \"partner_settings.new_relic.update\",\n \"partner_settings.read\",\n \"stats.global.read\",\n \"stats.read\",\n \"subusers.create\",\n \"subusers.credits.create\",\n \"subusers.credits.delete\",\n \"subusers.credits.read\",\n \"subusers.credits.remaining.create\",\n \"subusers.credits.remaining.delete\",\n \"subusers.credits.remaining.read\",\n \"subusers.credits.remaining.update\",\n \"subusers.credits.update\",\n \"subusers.delete\",\n \"subusers.monitor.create\",\n \"subusers.monitor.delete\",\n \"subusers.monitor.read\",\n \"subusers.monitor.update\",\n \"subusers.read\",\n \"subusers.reputations.read\",\n \"subusers.stats.monthly.read\",\n \"subusers.stats.read\",\n \"subusers.stats.sums.read\",\n \"subusers.summary.read\",\n \"subusers.update\",\n \"suppression.blocks.create\",\n \"suppression.blocks.delete\",\n \"suppression.blocks.read\",\n \"suppression.blocks.update\",\n \"suppression.bounces.create\",\n \"suppression.bounces.delete\",\n \"suppression.bounces.read\",\n \"suppression.bounces.update\",\n \"suppression.create\",\n \"suppression.delete\",\n \"suppression.invalid_emails.create\",\n \"suppression.invalid_emails.delete\",\n \"suppression.invalid_emails.read\",\n \"suppression.invalid_emails.update\",\n \"suppression.read\",\n \"suppression.spam_reports.create\",\n \"suppression.spam_reports.delete\",\n \"suppression.spam_reports.read\",\n \"suppression.spam_reports.update\",\n \"suppression.unsubscribes.create\",\n \"suppression.unsubscribes.delete\",\n \"suppression.unsubscribes.read\",\n \"suppression.unsubscribes.update\",\n \"suppression.update\",\n \"teammates.create\",\n \"teammates.read\",\n \"teammates.update\",\n \"teammates.delete\",\n \"templates.create\",\n \"templates.delete\",\n \"templates.read\",\n \"templates.update\",\n \"templates.versions.activate.create\",\n \"templates.versions.activate.delete\",\n \"templates.versions.activate.read\",\n \"templates.versions.activate.update\",\n \"templates.versions.create\",\n \"templates.versions.delete\",\n \"templates.versions.read\",\n \"templates.versions.update\",\n \"tracking_settings.click.read\",\n \"tracking_settings.click.update\",\n \"tracking_settings.google_analytics.read\",\n \"tracking_settings.google_analytics.update\",\n \"tracking_settings.open.read\",\n \"tracking_settings.open.update\",\n \"tracking_settings.read\",\n \"tracking_settings.subscription.read\",\n \"tracking_settings.subscription.update\",\n \"user.account.read\",\n \"user.credits.read\",\n \"user.email.create\",\n \"user.email.delete\",\n \"user.email.read\",\n \"user.email.update\",\n \"user.multifactor_authentication.create\",\n \"user.multifactor_authentication.delete\",\n \"user.multifactor_authentication.read\",\n \"user.multifactor_authentication.update\",\n \"user.password.read\",\n \"user.password.update\",\n \"user.profile.read\",\n \"user.profile.update\",\n \"user.scheduled_sends.create\",\n \"user.scheduled_sends.delete\",\n \"user.scheduled_sends.read\",\n \"user.scheduled_sends.update\",\n \"user.settings.enforced_tls.read\",\n \"user.settings.enforced_tls.update\",\n \"user.timezone.read\",\n \"user.username.read\",\n \"user.username.update\",\n \"user.webhooks.event.settings.read\",\n \"user.webhooks.event.settings.update\",\n \"user.webhooks.event.test.create\",\n \"user.webhooks.event.test.read\",\n \"user.webhooks.event.test.update\",\n \"user.webhooks.parse.settings.create\",\n \"user.webhooks.parse.settings.delete\",\n \"user.webhooks.parse.settings.read\",\n \"user.webhooks.parse.settings.update\",\n \"user.webhooks.parse.stats.read\",\n \"whitelabel.create\",\n \"whitelabel.delete\",\n \"whitelabel.read\",\n \"whitelabel.update\"\n]\n```", - "public": true - }, - "on-behalf-of": { - "id": "on-behalf-of", - "name": "On Behalf of Subuser", - "content": "Use the *on-behalf-of* header to make calls for a particular subuser through the parent account. Use this header to automate bulk updates, or to administer a subuser without changing the authentication in your code.\n\nTo use the feature, add the *on-behalf-of* header:\n\n`on-behalf-of: << subuser username >>`\n\nThis header generates the API call as if the subuser account was making the call.\n\nWhen authenticating using the *on-behalf-of* header, you need to use the API key credentials of the **parent account**. For example:\n\n```curl --request GET \\\n --url 'https://api.sendgrid.com/v3/stats?start_date=2018-02-01&aggregated_by=day' \\\n --header 'authorization: Bearer << API KEY >>' \\\n --header 'on-behalf-of: << subuser username >>'\n ```\n\n**Note**: The *on-behalf-of* header does not work with the mail.send API.", - "public": true - }, - "tip": { - "id": "tip", - "name": "Tip", - "content": "Exporting your contacts regularly as a backup to avoid issues is a recommended best practice.", - "public": true - } - }, - "mock": { - "enabled": false, - "dynamic": false - } - }, - "x-tests": { - "2QtdGPeZcwPm7CTTh": { - "id": "2QtdGPeZcwPm7CTTh", - "name": "Alerts test", - "initialVariables": {}, - "steps": [ - { - "id": "LrnrTjuMQ2kCb9xZG", - "name": "Create a new Alert", - "capture": { - "body": [ - { - "name": "alert_id", - "value": "id" - } - ] - }, - "request": { - "queryString": [], - "postData": { - "mimeType": "application/json", - "params": [], - "text": "{\n \"type\": \"stats_notification\",\n \"email_to\": \"example@example.com\",\n \"frequency\": \"daily\"\n}" - }, - "authentication": {}, - "method": "post", - "url": "/alerts", - "headers": [ - { - "value": "Bearer SG.xxxxxxxx.yyyyyyyy", - "name": "Authorization" - } - ], - "valid": 2, - "transformed": false, - "pathParams": [], - "cookies": [], - "headersSize": -1, - "bodySize": -1 - }, - "assertions": [ - { - "op": "eq", - "location": "response.code", - "expected": 201 - }, - { - "op": "validate.pass", - "match": 201, - "location": "response.body" - } - ] - }, - { - "id": "aRd37ou83TsrHxkMc", - "name": "Retrieve a specific alert", - "capture": {}, - "request": { - "method": "get", - "url": "/alerts/{alert_id}", - "headers": [ - { - "name": "Authorization", - "value": "Bearer SG.xxxxxxxx.yyyyyyyy" - } - ], - "queryString": [], - "postData": {}, - "authentication": {}, - "valid": 2, - "transformed": false, - "pathParams": [], - "cookies": [], - "headersSize": -1, - "bodySize": -1 - }, - "assertions": [ - { - "op": "eq", - "location": "response.code", - "expected": 200 - }, - { - "op": "validate.pass", - "match": 200, - "location": "response.body" - } - ] - }, - { - "id": "nqDiBRakuZA8nD6s7", - "name": "Update an alert", - "capture": {}, - "request": { - "method": "patch", - "url": "/alerts/{alert_id}", - "headers": [ - { - "name": "Authorization", - "value": "Bearer SG.xxxxxxxx.yyyyyyyy" - } - ], - "queryString": [], - "postData": { - "mimeType": "application/json", - "params": [], - "text": "{\n \"email_to\": \"matt@example.com\"\n}" - }, - "authentication": {}, - "valid": 2, - "transformed": false, - "pathParams": [], - "cookies": [], - "headersSize": -1, - "bodySize": -1 - }, - "assertions": [ - { - "op": "eq", - "location": "response.code", - "expected": 200 - }, - { - "op": "validate.pass", - "match": 200, - "location": "response.body" - } - ] - }, - { - "id": "MvuQwBuikXtWbsCBt", - "name": "Delete an alert", - "capture": {}, - "request": { - "method": "delete", - "url": "/alerts/{alert_id}", - "headers": [ - { - "name": "Authorization", - "value": "Bearer SG.xxxxxxxx.yyyyyyyy" - } - ], - "queryString": [], - "postData": {}, - "authentication": {}, - "valid": 2, - "transformed": false, - "pathParams": [], - "cookies": [], - "headersSize": -1, - "bodySize": -1 - }, - "assertions": [ - { - "op": "eq", - "location": "response.code", - "expected": 204 - }, - { - "op": "validate.pass", - "match": 204, - "location": "response.body" - } - ] - }, - { - "id": "kuh6nzo9sAfXJeSzz", - "name": "Create an alert", - "capture": {}, - "request": { - "authentication": {}, - "method": "post", - "url": "/alerts", - "headers": [ - { - "name": "Authorization", - "value": "Bearer SG.xxxxxxxx.yyyyyyyy" - } - ], - "queryString": [], - "postData": { - "mimeType": "application/json", - "params": [], - "text": "{\n \"type\": \"stats_notification\",\n \"email_to\": \"example@example.com\",\n \"frequency\": \"daily\"\n}" - }, - "valid": 2, - "transformed": false, - "pathParams": [], - "cookies": [], - "headersSize": -1, - "bodySize": -1 - }, - "assertions": [ - { - "op": "eq", - "location": "response.code", - "expected": 400 - }, - { - "op": "validate.pass", - "match": 400, - "location": "response.body" - } - ] - } - ] - }, - "HFGvnuoqkd36FarWE": { - "id": "HFGvnuoqkd36FarWE", - "name": "Parse Settings Test", - "initialVariables": {}, - "steps": [ - { - "id": "DXFjNLuibt8mBTMDE", - "name": "Create a parse setting", - "capture": { - "body": [ - { - "name": "hostname", - "value": "hostname" - } - ] - }, - "request": { - "method": "post", - "url": "/user/webhooks/parse/settings", - "headers": [ - { - "name": "Authorization", - "value": "Bearer SG.xxxxxxxx.yyyyyyyy" - } - ], - "queryString": [], - "postData": { - "mimeType": "application/json", - "params": [], - "text": "{\n \"hostname\": \"example.com\",\n \"url\": \"http://email.example.com\",\n \"spam_check\": true,\n \"send_raw\": false\n}" - }, - "authentication": {}, - "valid": 2, - "transformed": false, - "pathParams": [], - "cookies": [], - "headersSize": -1, - "bodySize": -1 - }, - "assertions": [ - { - "op": "eq", - "location": "response.code", - "expected": 201 - }, - { - "op": "validate.pass", - "match": 201, - "location": "response.body" - } - ] - }, - { - "id": "6DoSn3KYqs3LqNzo4", - "name": "Retrieve all parse settings", - "capture": {}, - "request": { - "method": "get", - "url": "/user/webhooks/parse/settings", - "headers": [ - { - "value": "Bearer SG.xxxxxxxx.yyyyyyyy", - "name": "Authorization" - } - ], - "queryString": [], - "postData": {}, - "authentication": {}, - "valid": 2, - "transformed": false, - "pathParams": [], - "cookies": [], - "headersSize": -1, - "bodySize": -1 - }, - "assertions": [ - { - "op": "eq", - "location": "response.code", - "expected": 200 - }, - { - "op": "validate.pass", - "match": 200, - "location": "response.body" - } - ] - }, - { - "id": "sXYsGopzxCdmtFBpf", - "name": "Retrieve a specific parse setting", - "capture": {}, - "request": { - "postData": {}, - "authentication": {}, - "method": "get", - "url": "/user/webhooks/parse/settings/{hostname}", - "headers": [ - { - "value": "Bearer SG.xxxxxxxx.yyyyyyyy", - "name": "Authorization" - } - ], - "queryString": [], - "valid": 2, - "transformed": false, - "pathParams": [], - "cookies": [], - "headersSize": -1, - "bodySize": -1 - }, - "assertions": [ - { - "op": "eq", - "location": "response.code", - "expected": 200 - }, - { - "op": "validate.pass", - "match": 200, - "location": "response.body" - } - ] - }, - { - "id": "AL2R3B5fyfMcLKvFg", - "name": "Update a parse setting", - "capture": {}, - "request": { - "method": "patch", - "url": "/user/webhooks/parse/settings/{hostname}/", - "headers": [ - { - "name": "Authorization", - "value": "Bearer SG.xxxxxxxx.yyyyyyyy" - } - ], - "queryString": [], - "postData": { - "text": "{\n \"url\": \"http://newdomain.com/parse\",\n \"spam_check\": false,\n \"send_raw\": true\n}", - "mimeType": "application/json", - "params": [] - }, - "authentication": {}, - "valid": 2, - "transformed": false, - "pathParams": [], - "cookies": [], - "headersSize": -1, - "bodySize": -1 - }, - "assertions": [ - { - "op": "eq", - "location": "response.code", - "expected": 200 - }, - { - "op": "validate.pass", - "match": 200, - "location": "response.body" - } - ] - }, - { - "id": "7ewLowiXP3fFti63Z", - "name": "Verify updating a parse setting", - "afterScript": "function (ctx, request, response) {\n // Your javascript code here.\n // Code completion enabled.\n // You have access to a global \"SL\" object.\n // \"url\": \"http://newdomain.com/parse\",\n // \"spam_check\": false,\n // \"send_raw\": true\n var body = response.body.get();\n assert.equal(body.url, \"http://newdomain.com/parse\");\n assert.equal(body.spam_check, false);\n assert.equal(body.send_raw, true);\n}", - "capture": {}, - "request": { - "url": "/user/webhooks/parse/settings/{hostname}", - "headers": [ - { - "name": "Authorization", - "value": "Bearer SG.xxxxxxxx.yyyyyyyy" - } - ], - "queryString": [], - "postData": {}, - "authentication": {}, - "method": "get", - "valid": 2, - "transformed": false, - "pathParams": [], - "cookies": [], - "headersSize": -1, - "bodySize": -1 - }, - "assertions": [ - { - "op": "eq", - "location": "response.code", - "expected": 200 - }, - { - "op": "validate.pass", - "match": 200, - "location": "response.body" - } - ] - }, - { - "id": "738KySxu4mWHjDvmw", - "name": "Delete a parse setting", - "capture": {}, - "request": { - "postData": { - "text": "{}", - "mimeType": "application/json", - "params": [] - }, - "authentication": {}, - "method": "delete", - "url": "/user/webhooks/parse/settings/{hostname}", - "headers": [ - { - "value": "Bearer SG.xxxxxxxx.yyyyyyyy", - "name": "Authorization" - } - ], - "queryString": [], - "valid": 2, - "transformed": false, - "pathParams": [], - "cookies": [], - "headersSize": -1, - "bodySize": -1 - }, - "assertions": [ - { - "op": "eq", - "location": "response.code", - "expected": 204 - }, - { - "op": "validate.pass", - "match": 204, - "location": "response.body" - } - ] - } - ] - } - }, - "servers": [ - { - "url": "http://api.sendgrid.com/v3" - } - ], - "components": { - "parameters": { - "trait_onBehalfOfSubuser_on-behalf-of": { - "name": "on-behalf-of", - "in": "header", - "schema": { - "type": "string", - "default": "The subuser's username. This header generates the API call as if the subuser account was making the call." - } - }, - "trait_baseParams_aggregated_by": { - "name": "aggregated_by", - "in": "query", - "description": "Dictates how the stats are time-sliced. Currently, `\"total\"` and `\"day\"` are supported.", - "schema": { - "type": "string", - "enum": ["day", "total"], - "default": "total" - } - }, - "trait_baseParams_start_date": { - "name": "start_date", - "in": "query", - "description": "Format: `YYYY-MM-DD`. If this parameter is included, the stats' start date is included in the search.", - "schema": { - "type": "string", - "format": "date", - "default": "2021-01-01" - } - }, - "trait_baseParams_end_date": { - "name": "end_date", - "in": "query", - "description": "Format: `YYYY-MM-DD`.If this parameter is included, the stats' end date is included in the search.", - "schema": { - "type": "string", - "format": "date", - "default": "2021-12-31" - } - }, - "trait_baseParams_timezone": { - "name": "timezone", - "in": "query", - "description": "[IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones) string representing the timezone in which the stats are to be presented, e.g., \"America/Chicago\".", - "schema": { - "type": "string", - "default": "UTC" - } - }, - "trait_pagination_page_size": { - "name": "page_size", - "in": "query", - "description": "The number of elements you want returned on each page.", - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50 - } - }, - "trait_pagination_page_token": { - "name": "page_token", - "in": "query", - "description": "The stats endpoints are paginated. To get the next page, call the passed `_metadata.next` URL. If `_metadata.prev` doesn't exist, you're at the first page. Similarly, if `_metadata.next` is not present, you're at the last page.", - "schema": { - "type": "string" - } - }, - "trait_singlesendQueryParams_group_by": { - "name": "group_by", - "in": "query", - "description": "A/B Single Sends have multiple variation IDs and phase IDs. Including these additional fields allows further granularity of stats by these fields.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string", - "enum": ["ab_variation", "ab_phase"] - } - } - }, - "trait_automationQueryParams_group_by": { - "name": "group_by", - "in": "query", - "description": "Automations can have multiple steps. Including `step_id` as a `group_by` metric allows further granularity of stats.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string", - "enum": ["step_id"] - } - } - }, - "trait_automationQueryParams_step_ids": { - "name": "step_ids", - "in": "query", - "description": "Comma-separated list of `step_ids` that you want the link stats for.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string", - "format": "uuid" - }, - "uniqueItems": true - } - }, - "trait_singlesendQueryParams2_group_by": { - "name": "group_by", - "in": "query", - "description": "A/B Single Sends have multiple variation IDs and phase IDs. Including these additional fields allows further granularity of stats by these fields.", - "style": "form", - "explode": false, - "schema": { - "type": "array", - "items": { - "type": "string", - "enum": ["ab_variation", "ab_phase"] - } - } - }, - "trait_singlesendQueryParams2_ab_variation_id": { - "name": "ab_variation_id", - "in": "query", - "schema": { - "type": "string", - "format": "uuid" - } - }, - "trait_singlesendQueryParams2_ab_phase_id": { - "name": "ab_phase_id", - "in": "query", - "schema": { - "type": "string", - "enum": ["test", "send"] - } - }, - "trait_statsAdvancedStatsBaseQueryStrings_start_date": { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "schema": { - "type": "string" - } - }, - "trait_statsAdvancedStatsBaseQueryStrings_end_date": { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "schema": { - "type": "string" - } - }, - "trait_statsAdvancedStatsBaseQueryStrings_aggregated_by": { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "schema": { - "type": "string", - "enum": ["day", "week", "month"] - } - }, - "trait_statsAdvancedQueryStringsLimitOffset_limit": { - "name": "limit", - "in": "query", - "description": "The number of results to return.", - "required": false, - "schema": { - "type": "integer" - } - }, - "trait_statsAdvancedQueryStringsLimitOffset_offset": { - "name": "offset", - "in": "query", - "description": "The point in the list to begin retrieving results.", - "required": false, - "schema": { - "type": "integer" - } - }, - "trait_statsAdvancedQueryStringsLimitOffset_aggregated_by": { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "schema": { - "type": "string", - "enum": ["day", "week", "month"] - } - }, - "trait_statsAdvancedQueryStringsLimitOffset_start_date": { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "schema": { - "type": "string" - } - }, - "trait_statsAdvancedQueryStringsLimitOffset_end_date": { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "schema": { - "type": "string" - } - }, - "trait_designsQueryStrings_page_size": { - "name": "page_size", - "in": "query", - "description": "number of results to return", - "schema": { - "type": "integer", - "minimum": 0, - "default": 100 - } - }, - "trait_designsQueryStrings_page_token": { - "name": "page_token", - "in": "query", - "description": "token corresponding to a specific page of results, as provided by metadata", - "schema": { - "type": "string" - } - }, - "trait_designsQueryStrings_summary": { - "name": "summary", - "in": "query", - "description": "set to false to return all fields", - "schema": { - "type": "boolean", - "default": true - } - }, - "trait_authorizationHeader_Authorization": { - "name": "Authorization", - "in": "header", - "required": true, - "schema": { - "type": "string", - "default": "Bearer <>" - } - } - }, - "responses": { - "trait_errorResponse_400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - }, - "trait_pagination_200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "_metadata": { - "$ref": "#/components/schemas/metadata" - } - } - } - } - } - }, - "trait_mailSendErrors_400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - }, - "trait_mailSendErrors_413": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - }, - "trait_globalErrors_401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - }, - "trait_globalErrors_403": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - }, - "trait_globalErrors_404": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - }, - "trait_globalErrors_500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - } - } - } - } - } - } - } - } - }, - "trait_cancelScheduledSendsErrors_400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - }, - "help": { - "type": "object" - } - } - } - }, - "id": { - "type": "string" - } - } - } - } - } - }, - "trait_apiKeysErrors_400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - }, - "trait_apiKeysErrors_403": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - }, - "trait_apiKeysErrors_404": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/global_error_response_schema" - } - } - } - }, - "trait_makoErrorResponse_400": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "error_id": { - "type": "string", - "description": "The ID associated with the error." - }, - "field": { - "description": "The field that generated the error.", - "nullable": true, - "type": "string" - }, - "message": { - "type": "string", - "description": "The error message." - }, - "parameter": { - "type": "string" - } - }, - "required": ["message"] - } - } - } - } - } - } - }, - "trait_makoErrorResponse_401": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "error_id": { - "type": "string", - "description": "The ID associated with the error." - }, - "field": { - "description": "The field that generated the error.", - "nullable": true, - "type": "string" - }, - "message": { - "type": "string", - "description": "The error message." - }, - "parameter": { - "type": "string" - } - }, - "required": ["message"] - } - } - } - } - } - } - }, - "trait_makoErrorResponse_403": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "error_id": { - "type": "string", - "description": "The ID associated with the error." - }, - "field": { - "description": "The field that generated the error.", - "nullable": true, - "type": "string" - }, - "message": { - "type": "string", - "description": "The error message." - }, - "parameter": { - "type": "string" - } - }, - "required": ["message"] - } - } - } - } - } - } - }, - "trait_makoErrorResponse_404": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "error_id": { - "type": "string", - "description": "The ID associated with the error." - }, - "field": { - "description": "The field that generated the error.", - "nullable": true, - "type": "string" - }, - "message": { - "type": "string", - "description": "The error message." - }, - "parameter": { - "type": "string" - } - }, - "required": ["message"] - } - } - } - } - } - } - }, - "trait_makoErrorResponse_500": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "error_id": { - "type": "string", - "description": "The ID associated with the error." - }, - "field": { - "description": "The field that generated the error.", - "nullable": true, - "type": "string" - }, - "message": { - "type": "string", - "description": "The error message." - }, - "parameter": { - "type": "string" - } - }, - "required": ["message"] - } - } - } - } - } - } - }, - "trait_singleSignOnErrorsTrait_400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-error-response" - } - } - } - }, - "trait_singleSignOnErrorsTrait_401": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-error-response" - } - } - } - }, - "trait_singleSignOnErrorsTrait_403": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-error-response" - } - } - } - }, - "trait_singleSignOnErrorsTrait_429": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-error-response" - } - } - } - }, - "trait_singleSignOnErrorsTrait_500": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/sso-error-response" - } - } - } - }, - "trait_errors_400": { - "description": "", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/errors-seg-v2" - } - } - } - }, - "trait_errors_404": { - "description": "" - }, - "trait_errors_500": { - "description": "" - } - }, - "requestBodies": { - "segment_write_v2": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/segment_write_v2" - } - } - } - }, - "design-duplicate-input": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/design-duplicate-input" - } - } - } - }, - "singlesend_request": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/singlesend_request" - } - } - } - }, - "create-integration-request": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/create-integration-request" - } - } - } - }, - "monitor": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/monitor" - } - } - } - }, - "verified-sender-request-schema": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/verified-sender-request-schema" - } - } - } - }, - "DELETE_contactdb-lists-list_idBody": { - "content": { - "application/json": { - "schema": { - "nullable": true - } - } - } - }, - "transactional_template_version_create": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/transactional_template_version_create" - } - } - } - }, - "parse-setting": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/parse-setting" - } - } - } - }, - "suppressions-request": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/suppressions-request" - } - } - } - } - }, - "securitySchemes": { - "Authorization": { - "name": "Authorization", - "type": "apiKey", - "in": "header" - } - }, - "schemas": { - "partner_settings_new_relic": { - "title": "Partner Settings: New Relic", - "type": "object", - "properties": { - "enable_subuser_statistics": { - "type": "boolean", - "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this setting is enabled. " - }, - "license_key": { - "type": "string", - "description": "The license key provided with your New Relic account." - } - }, - "required": ["enabled", "license_key"], - "x-stoplight": { - "id": "partner_settings_new_relic", - "name": "Partner Settings: New Relic", - "public": true - } - }, - "subscription_tracking_settings": { - "title": "Settings: Subscription Tracking", - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if subscription tracking is enabled." - }, - "html_content": { - "type": "string", - "description": "The information and HTML for your unsubscribe link. " - }, - "landing": { - "type": "string", - "description": "The HTML that will be displayed on the page that your customers will see after clicking unsubscribe, hosted on SendGrid’s server." - }, - "plain_content": { - "type": "string", - "description": "The information in plain text for your unsubscribe link. You should have the “<% %>” tag in your content, otherwise the user will have no URL for unsubscribing." - }, - "replace": { - "type": "string", - "description": "Your custom defined replacement tag for your templates. Use this tag to place your unsubscribe content anywhere in your emailtemplate." - }, - "url": { - "type": "string", - "description": "The URL where you would like your users sent to unsubscribe.", - "format": "uri" - } - }, - "x-stoplight": { - "id": "subscription_tracking_settings", - "name": "Settings: Subscription Tracking", - "public": true - } - }, - "contactdb_recipient_response": { - "title": "ContactDB: Recipient response", - "type": "object", - "properties": { - "error_count": { - "type": "number", - "default": 0, - "description": "The number of errors found while adding recipients." - }, - "error_indices": { - "type": "array", - "default": [], - "description": "The indices of the recipient(s) sent that caused the error. ", - "items": { - "type": "number" - } - }, - "new_count": { - "type": "number", - "default": 0, - "description": "The count of new recipients added to the contactdb." - }, - "persisted_recipients": { - "type": "array", - "default": [], - "description": "The recipient IDs of the recipients that already existed from this request.", - "items": { - "type": "string" - } - }, - "updated_count": { - "type": "number", - "default": 0, - "description": "The recipients who were updated from this request." - }, - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "error_indices": { - "type": "array", - "items": { - "type": "number" - } - } - } - } - } - }, - "required": ["error_count", "new_count", "persisted_recipients", "updated_count"], - "example": { - "error_count": 1, - "error_indices": [2], - "new_count": 2, - "persisted_recipients": ["YUBh", "bWlsbGVyQG1pbGxlci50ZXN0"], - "updated_count": 0, - "errors": [ - { - "message": "Invalid email.", - "error_indices": [2] - } - ] - }, - "x-stoplight": { - "id": "contactdb_recipient_response", - "name": "ContactDB: Recipient response", - "public": true - } - }, - "campaign_response": { - "title": "Campaigns Response", - "allOf": [ - { - "$ref": "#/components/schemas/campaign_request" - }, - { - "type": "object", - "properties": { - "status": { - "type": "string", - "description": "The status of your campaign." - }, - "id": { - "type": "integer" - } - }, - "required": ["status"] - } - ], - "x-stoplight": { - "id": "campaign_response", - "name": "Campaigns Response", - "public": true - } - }, - "contactdb_segments_conditions": { - "title": "ContactDB: Segments: Conditions", - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "value": { - "type": "string" - }, - "operator": { - "type": "string", - "enum": ["eq", "ne", "lt", "gt", "contains"] - }, - "and_or": { - "type": "string", - "enum": ["and", "or", ""] - } - }, - "required": ["field", "value", "operator"], - "x-stoplight": { - "id": "contactdb_segments_conditions", - "name": "ContactDB: Segments: Conditions", - "public": true - } - }, - "bounce_response": { - "title": "Bounce Response", - "type": "object", - "properties": { - "created": { - "type": "number", - "description": "The unix timestamp for when the bounce record was created at SendGrid." - }, - "email": { - "type": "string", - "format": "email", - "description": "The email address that was added to the bounce list." - }, - "reason": { - "type": "string", - "description": "The reason for the bounce. This typically will be a bounce code, an enhanced code, and a description." - }, - "status": { - "type": "string", - "description": "Enhanced SMTP bounce response" - } - }, - "example": { - "created": 1250337600, - "email": "example@example.com", - "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ", - "status": "5.1.1" - }, - "x-stoplight": { - "id": "bounce_response", - "name": "Bounce Response", - "public": true - } - }, - "contacts": { - "title": "Contacts", - "type": "object", - "properties": { - "address": { - "type": "string" - }, - "address2": { - "type": "object" - }, - "city": { - "type": "string" - }, - "company": { - "type": "string" - }, - "country": { - "type": "string" - }, - "email": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "phone": { - "type": "string" - }, - "state": { - "type": "string" - }, - "zip": { - "type": "string" - } - }, - "x-stoplight": { - "id": "contacts", - "name": "Contacts", - "public": true - } - }, - "reverse_dns": { - "title": "Reverse DNS", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the Reverse DNS." - }, - "ip": { - "type": "string", - "description": "The IP address that this Reverse DNS was created for." - }, - "rdns": { - "type": "string", - "description": "The reverse DNS record for the IP address. This points to the Reverse DNS subdomain." - }, - "users": { - "type": "array", - "description": "The users who are able to send mail from the IP address.", - "items": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username of a user who can send mail from the IP address." - }, - "user_id": { - "type": "integer", - "description": "The ID of a user who can send mail from the IP address." - } - }, - "required": ["username", "user_id"] - } - }, - "subdomain": { - "type": "string", - "description": "The subdomain created for this reverse DNS. This is where the rDNS record points." - }, - "domain": { - "type": "string", - "description": "The root, or sending, domain." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid Reverse DNS." - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this Reverse DNS was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you'll need to create a new Reverse DNS if you need to update it." - }, - "last_validation_attempt_at": { - "type": "integer", - "description": "A Unix epoch timestamp representing the last time of a validation attempt." - }, - "a_record": { - "type": "object", - "required": ["valid", "type", "host", "data"], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the a_record is valid." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "This is the web address that will be mapped to the IP address." - }, - "data": { - "type": "string", - "description": "The IP address being set up with Reverse DNS." - } - } - } - }, - "required": ["id", "ip", "rdns", "users", "domain", "valid", "legacy", "a_record"], - "example": { - "id": 1, - "ip": "192.168.1.1", - "rdns": "o1.email.example.com", - "users": [ - { - "username": "john@example.com", - "user_id": 7 - }, - { - "username": "jane@example.com", - "user_id": 8 - } - ], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o1.email.example.com", - "data": "192.168.1.1" - } - }, - "x-stoplight": { - "id": "reverse_dns", - "name": "Reverse DNS", - "public": true - } - }, - "senderID": { - "title": "Sender ID", - "allOf": [ - { - "$ref": "#/components/schemas/sender-id-request" - }, - { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The unique identifier of the sender identity." - }, - "verified": { - "type": "boolean", - "description": "If the sender identity is verified or not. Only verified sender identities can be used to send email." - }, - "updated_at": { - "type": "integer", - "description": "The time the sender identity was last updated." - }, - "created_at": { - "type": "integer", - "description": "The time the sender identity was created." - }, - "locked": { - "type": "boolean", - "description": "True when the sender id is associated to a campaign in the Draft, Scheduled, or In Progress status. You cannot update or delete a locked sender identity." - } - } - }, - { - "type": "object", - "required": ["nickname", "address", "city", "country"] - } - ], - "example": { - "id": 1, - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States", - "verified": true, - "updated_at": 1449872165, - "created_at": 1449872165, - "locked": false - }, - "x-stoplight": { - "id": "senderID", - "name": "Sender ID", - "public": true - } - }, - "contactdb_custom_field": { - "title": "ContactDB Custom field schema.", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the field" - }, - "type": { - "type": "string", - "description": "The type of the field.", - "enum": ["date", "text", "number"] - } - }, - "example": { - "name": "first_name", - "type": "text" - }, - "x-stoplight": { - "id": "contactdb_custom_field", - "name": "ContactDB: Custom Field", - "public": true - } - }, - "subuser": { - "title": "List all Subusers for a parent response", - "type": "object", - "properties": { - "disabled": { - "type": "boolean", - "description": "Whether or not the user is enabled or disabled." - }, - "id": { - "type": "number", - "description": "The ID of this subuser." - }, - "username": { - "type": "string", - "description": "The name by which this subuser will be referred." - }, - "email": { - "type": "string", - "description": "The email address to contact this subuser.", - "format": "email" - } - }, - "required": ["disabled", "id", "username", "email"], - "example": { - "disabled": false, - "email": "example@example.com", - "id": 1234, - "username": "example_subuser" - }, - "x-stoplight": { - "id": "subuser", - "name": "Subuser", - "public": true - } - }, - "mail_settings_address_whitelabel": { - "title": "Mail Settings: Address Whitelabel", - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if you have an email address whitelist enabled. " - }, - "list": { - "type": "array", - "description": "All email addresses that are currently on the whitelist.", - "items": { - "type": "string" - } - } - }, - "example": { - "enabled": true, - "list": ["email1@example.com", "example.com"] - }, - "x-stoplight": { - "id": "mail_settings_address_whitelabel", - "name": "Mail Settings: Address Whitelabel", - "public": true - } - }, - "link_branding_200_response": { - "title": "Link Branding 200 Response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the branded link." - }, - "domain": { - "type": "string", - "description": "The root domain of the branded link." - }, - "subdomain": { - "type": "string", - "description": "The subdomain used to generate the DNS records for this link branding. This subdomain must be different from the subdomain used for your authenticated domain." - }, - "username": { - "type": "string", - "description": "The username of the account that this link branding is associated with." - }, - "user_id": { - "type": "integer", - "description": "The ID of the user that this link branding is associated with." - }, - "default": { - "type": "boolean", - "description": "Indicates if this is the default link branding.", - "enum": [true, false] - }, - "valid": { - "type": "boolean", - "description": "Indicates if this link branding is valid.", - "enum": [true, false] - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this link branding was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you'll need to create new link branding if you need to update it.", - "enum": [true, false] - }, - "dns": { - "type": "object", - "description": "The DNS records generated for this link branding.", - "required": ["domain_cname"], - "properties": { - "domain_cname": { - "type": "object", - "description": "The DNS record generated to point to your link branding subdomain.", - "required": ["valid", "type", "host", "data"], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid.", - "enum": [true, false] - }, - "type": { - "type": "string", - "description": "The type of DNS record that was generated.", - "enum": ["cname", "txt", "mx"] - }, - "host": { - "type": "string", - "description": "The domain that this link branding will use for the links in your email." - }, - "data": { - "type": "string", - "description": "The domain that the DNS record points to." - } - } - }, - "owner_cname": { - "type": "object", - "description": "The DNS record generated to verify who created the link branding.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid.", - "enum": [true, false] - }, - "type": { - "type": "string", - "description": "The type of DNS record generated.", - "enum": ["cname", "txt", "mx"] - }, - "host": { - "type": "string", - "description": "Used to verify the link branding. The subdomain of this domain is the ID of the user who created the link branding." - }, - "data": { - "type": "string", - "description": "The domain that the DNS record points to." - } - }, - "required": ["valid", "host", "data"] - } - } - } - }, - "required": ["id", "domain", "username", "user_id", "default", "valid", "legacy", "dns"], - "x-stoplight": { - "id": "link_branding_200_response", - "name": "Link Branding 200 Response", - "public": true - } - }, - "from_email_object": { - "title": "From Email Object", - "type": "object", - "properties": { - "email": { - "type": "string", - "format": "email", - "description": "The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account." - }, - "name": { - "type": "string", - "description": "A name or title associated with the sending email address." - } - }, - "required": ["email"], - "example": { - "email": "jane_doe@example.com", - "name": "Jane Doe" - }, - "x-stoplight": { - "id": "from_email_object", - "name": "From Email Object", - "public": true - } - }, - "api_key_name_id_scopes": { - "title": "API Key Name, ID, and Scopes", - "allOf": [ - { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "The permissions this API Key has access to.", - "items": { - "type": "string" - } - } - } - }, - { - "$ref": "#/components/schemas/api_key_name_id" - } - ], - "example": { - "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", - "name": "Mail Send", - "scopes": [ - "mail.send", - "mail.batch.create", - "mail.batch.read", - "mail.batch.update", - "mail.batch.delete", - "user.scheduled_sends.create", - "user.scheduled_sends.read", - "user.scheduled_sends.update", - "user.scheduled_sends.delete", - "sender_verification_eligible", - "sender_verification_legacy", - "2fa_required" - ] - }, - "x-stoplight": { - "id": "api_key_name_id_scopes", - "name": "API Key Name, ID, and Scopes", - "public": true - } - }, - "contactdb_segments": { - "title": "Create a Segment request", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of this segment." - }, - "list_id": { - "type": "integer", - "description": "The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list." - }, - "conditions": { - "type": "array", - "description": "The conditions for a recipient to be included in this segment.", - "items": { - "$ref": "#/components/schemas/contactdb_segments_conditions" - } - }, - "recipient_count": { - "type": "number", - "description": "The count of recipients in this list. This is not included on creation of segments." - } - }, - "required": ["name", "conditions"], - "example": { - "name": "Last Name Miller", - "list_id": 4, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - }, - { - "field": "last_clicked", - "value": "01/02/2015", - "operator": "gt", - "and_or": "and" - }, - { - "field": "clicks.campaign_identifier", - "value": "513", - "operator": "eq", - "and_or": "or" - } - ], - "recipient_count": 1234 - }, - "x-stoplight": { - "id": "contactdb_segments", - "name": "ContactDB: Segments", - "public": true - } - }, - "api_key_name_id": { - "title": "API Key Name and ID", - "type": "object", - "properties": { - "api_key_id": { - "type": "string", - "description": "The ID of your API Key. " - }, - "name": { - "type": "string", - "description": "The name of your API Key." - } - }, - "example": { - "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", - "name": "Mail Send" - }, - "x-stoplight": { - "id": "api_key_name_id", - "name": "API Key Name and ID", - "public": true - } - }, - "advanced_stats_opens": { - "title": "Stats: Advanced Stats with Opens", - "type": "object", - "description": "The individual events and their stats.", - "properties": { - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - } - }, - "x-stoplight": { - "id": "advanced_stats_opens", - "name": "Stats: Advanced Stats with Opens", - "public": true - } - }, - "mail_settings_template": { - "title": "Mail Settings: Template", - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the legacy email template setting is enabled." - }, - "html_content": { - "type": "string", - "description": "The HTML content that you want to use for your legacy email template." - } - }, - "example": { - "enabled": false, - "html_content": "

<% body %>Example

\n" - }, - "x-stoplight": { - "id": "mail_settings_template", - "name": "Mail Settings: Template", - "public": true - } - }, - "ip_warmup_response": { - "title": "IP Warmup: IP", - "type": "array", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address." - }, - "start_date": { - "type": "integer", - "description": "A Unix timestamp indicating when the IP address entered warmup mode." - } - }, - "required": ["ip", "start_date"] - }, - "example": [ - { - "ip": "0.0.0.0", - "start_date": 1409616000 - } - ], - "x-stoplight": { - "id": "ip_warmup_response", - "name": "IP Warmup: IP", - "public": true - } - }, - "monitor": { - "title": "Create monitor settings request", - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address to which Sendgrid should send emails for monitoring.", - "format": "email" - }, - "frequency": { - "type": "number", - "description": "The frequency at which to forward monitoring emails. An email will be sent when your subuser sends this many (e.g., 1,000) emails." - } - }, - "required": ["email", "frequency"], - "example": { - "email": "example@example.com", - "frequency": 50000 - }, - "x-stoplight": { - "id": "monitor", - "name": "Monitor Settings", - "public": true - } - }, - "global_error_response_schema": { - "title": "Global Error Response Schema", - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "the error message" - }, - "field": { - "description": "the field that generated the error", - "nullable": true, - "type": "string" - }, - "help": { - "type": "object", - "description": "helper text or docs for troubleshooting" - } - }, - "required": ["message"] - } - }, - "id": { - "type": "string" - } - }, - "example": { - "errors": [ - { - "field": "field_name", - "message": "error message" - } - ] - }, - "x-stoplight": { - "id": "global_error_response_schema", - "name": "Global Error Response Schema", - "public": true - } - }, - "advanced_stats_mailbox_provider": { - "title": "Stats: Advanced Stats for Mailbox Provider", - "description": "The individual events and their stats.", - "allOf": [ - { - "$ref": "#/components/schemas/advanced_stats_clicks_opens" - }, - { - "type": "object", - "description": "The individual events and their stats.", - "properties": { - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "deferred": { - "type": "integer", - "description": "The number of emails that temporarily could not be delivered." - }, - "delivered": { - "type": "integer", - "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." - }, - "drops": { - "type": "integer", - "description": "The number of emails that were not delivered due to the recipient email address being on a suppression list." - }, - "requests": { - "type": "integer", - "description": "The number of emails that were requested to be delivered." - }, - "processed": { - "type": "integer", - "description": "Requests from your website, application, or mail client via SMTP Relay or the Web API that SendGrid processed." - }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." - } - } - } - ], - "x-stoplight": { - "id": "advanced_stats_mailbox_provider", - "name": "Stats: Advanced Stats for Mailbox Provider", - "public": true - } - }, - "contactdb_custom_field_with_id": { - "title": "ContactDB Custom field schema with ID.", - "allOf": [ - { - "$ref": "#/components/schemas/contactdb_custom_field" - }, - { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the custom field." - } - } - } - ], - "x-stoplight": { - "id": "contactdb_custom_field_with_id", - "name": "ContactDB: Custom Field with ID", - "public": true - } - }, - "ip_pool": { - "title": "IP Pools: Pool", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the IP pool.", - "maxLength": 64 - } - }, - "required": ["name"], - "x-stoplight": { - "id": "ip_pool", - "name": "IP Pools: Pool", - "public": true - } - }, - "google_analytics_settings": { - "title": "Settings: Google Analytics", - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if Google Analytics is enabled." - }, - "utm_campaign": { - "type": "string", - "description": "The name of the campaign." - }, - "utm_content": { - "type": "string", - "description": "Used to differentiate ads" - }, - "utm_medium": { - "type": "string", - "description": "Name of the marketing medium (e.g. \"Email\")." - }, - "utm_source": { - "type": "string", - "description": "Name of the referrer source. " - }, - "utm_term": { - "type": "string", - "description": "Any paid keywords." - } - }, - "example": { - "enabled": true, - "utm_source": "sendgrid.com", - "utm_medium": "email", - "utm_term": "", - "utm_content": "", - "utm_campaign": "website" - }, - "x-stoplight": { - "id": "google_analytics_settings", - "name": "Settings: Google Analytics", - "public": true - } - }, - "event-webhook-response": { - "title": "Webhooks: Event Webhook Response", - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the event webhook is enabled." - }, - "url": { - "type": "string", - "description": "The URL that you want the event webhook to POST to." - }, - "group_resubscribe": { - "type": "boolean", - "description": "Recipient resubscribes to specific group by updating preferences. You need to enable Subscription Tracking for getting this type of event." - }, - "delivered": { - "type": "boolean", - "description": "Message has been successfully delivered to the receiving server." - }, - "group_unsubscribe": { - "type": "boolean", - "description": "Recipient unsubscribe from specific group, by either direct link or updating preferences. You need to enable Subscription Tracking for getting this type of event." - }, - "spam_report": { - "type": "boolean", - "description": "Recipient marked a message as spam." - }, - "bounce": { - "type": "boolean", - "description": "Receiving server could not or would not accept message." - }, - "deferred": { - "type": "boolean", - "description": "Recipient's email server temporarily rejected message." - }, - "unsubscribe": { - "type": "boolean", - "description": "Recipient clicked on message's subscription management link. You need to enable Subscription Tracking for getting this type of event." - }, - "processed": { - "type": "boolean", - "description": "Message has been received and is ready to be delivered." - }, - "open": { - "type": "boolean", - "description": "Recipient has opened the HTML message. You need to enable Open Tracking for getting this type of event." - }, - "click": { - "type": "boolean", - "description": "Recipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event." - }, - "dropped": { - "type": "boolean", - "description": "You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota" - }, - "oauth_client_id": { - "type": "string", - "description": "The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token." - }, - "oauth_token_url": { - "type": "string", - "description": "The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider." - } - }, - "required": [ - "enabled", - "url", - "group_resubscribe", - "delivered", - "group_unsubscribe", - "spam_report", - "bounce", - "deferred", - "unsubscribe", - "processed", - "open", - "click", - "dropped" - ], - "x-stoplight": { - "id": "event-webhook-response", - "name": "Webhooks: Event Webhook Response", - "public": true - } - }, - "user_profile": { - "title": "User: Profile", - "type": "object", - "properties": { - "address": { - "type": "string", - "description": "The street address for this user profile." - }, - "address2": { - "type": "string", - "description": "An optional second line for the street address of this user profile." - }, - "city": { - "type": "string", - "description": "The city for the user profile." - }, - "company": { - "type": "string", - "description": "That company that this user profile is associated with." - }, - "country": { - "type": "string", - "description": "Th country of this user profile." - }, - "first_name": { - "type": "string", - "description": "The first name of the user." - }, - "last_name": { - "type": "string", - "description": "The last name of the user." - }, - "phone": { - "type": "string", - "description": "The phone number for the user." - }, - "state": { - "type": "string", - "description": "The state for this user." - }, - "website": { - "type": "string", - "description": "The website associated with this user." - }, - "zip": { - "type": "string", - "description": "The zip code for this user." - } - }, - "example": { - "address": "1451 Larimer Street, 3rd floor", - "address2": "", - "city": "Denver, CO", - "company": "SendGrid", - "country": "US", - "first_name": "Matthew", - "last_name": "Bernier", - "phone": "7208788003", - "state": "CO", - "website": "http://sendgrid.com", - "zip": "80202" - }, - "x-stoplight": { - "id": "user_profile", - "name": "User: Profile", - "public": true - } - }, - "mail_settings_footer": { - "title": "Mail Settings: Footer", - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the Footer mail setting is currently enabled." - }, - "html_content": { - "type": "string", - "description": "The custom HTML content of your email footer." - }, - "plain_content": { - "type": "string", - "description": "The plain text content of your email footer." - } - }, - "example": { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" - }, - "x-stoplight": { - "id": "mail_settings_footer", - "name": "Mail Settings: Footer", - "public": true - } - }, - "category_stats": { - "title": "Stats: Category Stats", - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date the statistics were gathered." - }, - "stats": { - "type": "array", - "items": { - "type": "object", - "properties": { - "metrics": { - "type": "object", - "properties": { - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounce_drops": { - "type": "integer", - "description": "The number of emails that were dropped because of a bounce." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "clicks": { - "type": "integer", - "description": "The number of links that were clicked." - }, - "deferred": { - "type": "integer", - "description": "The number of emails that temporarily could not be delivered." - }, - "delivered": { - "type": "integer", - "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." - }, - "invalid_emails": { - "type": "integer", - "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "processed": { - "type": "integer", - "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." - }, - "requests": { - "type": "integer", - "description": "The number of emails that were requested to be delivered." - }, - "spam_report_drops": { - "type": "integer", - "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." - }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - }, - "unsubscribe_drops": { - "type": "integer", - "description": "The number of emails dropped due to a recipient unsubscribing from your emails." - }, - "unsubscribes": { - "type": "integer", - "description": "The number of recipients who unsubscribed from your emails." - } - }, - "required": [ - "blocks", - "bounce_drops", - "bounces", - "clicks", - "deferred", - "delivered", - "invalid_emails", - "opens", - "processed", - "requests", - "spam_report_drops", - "spam_reports", - "unique_clicks", - "unique_opens", - "unsubscribe_drops", - "unsubscribes" - ] - }, - "name": { - "type": "string", - "description": "The name of the category." - }, - "type": { - "type": "string", - "description": "How you are segmenting your statistics." - } - }, - "required": ["type"] - } - } - }, - "required": ["date"], - "example": { - "date": "2015-01-01", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "cat1", - "type": "category" - }, - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "cat2", - "type": "category" - } - ] - }, - "x-stoplight": { - "id": "category_stats", - "name": "Stats: Category Stats", - "public": true - } - }, - "parse-setting": { - "title": "Parse Setting", - "type": "object", - "properties": { - "url": { - "type": "string", - "description": "The public URL where you would like SendGrid to POST the data parsed from your email. Any emails sent with the given hostname provided (whose MX records have been updated to point to SendGrid) will be parsed and POSTed to this URL." - }, - "hostname": { - "type": "string", - "description": "A specific and unique domain or subdomain that you have created to use exclusively to parse your incoming email. For example, `parse.yourdomain.com`." - }, - "spam_check": { - "type": "boolean", - "description": "Indicates if you would like SendGrid to check the content parsed from your emails for spam before POSTing them to your domain." - }, - "send_raw": { - "type": "boolean", - "description": "Indicates if you would like SendGrid to post the original MIME-type content of your parsed email. When this parameter is set to `true`, SendGrid will send a JSON payload of the content of your email." - } - }, - "example": { - "url": "http://email.myhostname.com", - "hostname": "myhostname.com", - "spam_check": false, - "send_raw": true - }, - "x-stoplight": { - "id": "parse-setting", - "name": "Parse Setting", - "public": true - } - }, - "transactional_template": { - "title": "Transactional Templates: Template", - "allOf": [ - { - "$ref": "#/components/schemas/transactional-templates-template-lean" - }, - { - "type": "object", - "properties": { - "warning": { - "$ref": "#/components/schemas/transactional-template-warning" - } - } - } - ], - "example": { - "id": "33feeff2-5069-43fe-8853-428651e5be79", - "name": "example_name", - "updated_at ": "2021-04-28 13:12:46", - "warning": { - "message": "Sample warning message" - }, - "generation": "legacy" - }, - "x-stoplight": { - "id": "transactional_template", - "name": "Transactional Templates: Template", - "public": true - } - }, - "contactdb_list": { - "title": "ContactDB lists", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The reference ID of your list." - }, - "name": { - "type": "string", - "description": "The name of your list. Must be unique against all other list and segment names." - }, - "recipient_count": { - "type": "integer", - "description": "The count of recipients currently in the list." - } - }, - "required": ["id", "name", "recipient_count"], - "example": { - "id": 1, - "name": "listname", - "recipient_count": 0 - }, - "x-stoplight": { - "id": "contactdb_list", - "name": "ContactDB: List", - "public": true - } - }, - "suppression_group": { - "title": "Suppressions: Suppression Group", - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The id of the suppression group." - }, - "name": { - "type": "string", - "description": "The name of the suppression group. Each group created by a user must have a unique name.", - "maxLength": 30 - }, - "description": { - "type": "string", - "description": "A description of the suppression group.", - "maxLength": 100 - }, - "last_email_sent_at": { - "type": "integer", - "nullable": true - }, - "is_default": { - "type": "boolean", - "default": false, - "description": "Indicates if this is the default suppression group." - }, - "unsubscribes": { - "type": "integer", - "description": "The unsubscribes associated with this group." - } - }, - "required": ["id", "name", "description"], - "x-stoplight": { - "id": "suppression_group", - "name": "Suppressions: Suppression Group", - "public": true - } - }, - "mail_settings_bounce_purge": { - "title": "Mail Settings: Bounce Purge", - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the bounce purge mail setting is enabled." - }, - "soft_bounces": { - "description": "The number of days after which SendGrid will purge all contacts from your soft bounces suppression lists.", - "nullable": true, - "type": "integer" - }, - "hard_bounces": { - "description": "The number of days after which SendGrid will purge all contacts from your hard bounces suppression lists.", - "nullable": true, - "type": "integer" - } - }, - "example": { - "enabled": false, - "soft_bounces": 1234, - "hard_bounces": null - }, - "x-stoplight": { - "id": "mail_settings_bounce_purge", - "name": "Mail Settings: Bounce Purge", - "public": true - } - }, - "transactional_template_version_output": { - "title": "Transactional Templates: Version Output", - "allOf": [ - { - "type": "object", - "properties": { - "warnings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/transactional-template-warning" - } - } - } - }, - { - "$ref": "#/components/schemas/transactional_template_version_create" - }, - { - "$ref": "#/components/schemas/transactional-templates-version-output-lean" - } - ], - "x-stoplight": { - "id": "transactional_template_version_output", - "name": "Transactional Templates: Version Output", - "public": true - } - }, - "credentials": { - "title": "Credentials", - "type": "object", - "properties": { - "permissions": { - "type": "object", - "properties": { - "api": { - "type": "string" - }, - "mail": { - "type": "string" - }, - "web": { - "type": "string" - } - } - }, - "username": { - "type": "string" - } - }, - "example": { - "address": "1234 example street", - "address2": null, - "city": "Denver", - "company": "Company name", - "country": "US", - "email": "example@example.com", - "first_name": "Example", - "last_name": "User", - "phone": "(555) 555-5555", - "state": "CO", - "zip": "55555" - }, - "x-stoplight": { - "id": "credentials", - "name": "Credentials", - "public": true - } - }, - "mail_settings_forward_spam": { - "title": "Mail Settings: Forward Spam", - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address where you would like the spam reports to be forwarded." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if the Forward Spam setting is enabled." - } - }, - "example": { - "email": "", - "enabled": true - }, - "x-stoplight": { - "id": "mail_settings_forward_spam", - "name": "Mail Settings: Forward Spam", - "public": true - } - }, - "campaign_request": { - "title": "Campaigns Request", - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI." - }, - "subject": { - "description": "The subject of your campaign that your recipients will see.", - "nullable": true, - "type": "string" - }, - "sender_id": { - "description": "The ID of the \"sender\" identity that you have created. Your recipients will see this as the \"from\" on your marketing emails.", - "nullable": true, - "type": "integer" - }, - "list_ids": { - "description": "The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs", - "items": { - "type": "integer" - }, - "nullable": true, - "type": "array" - }, - "segment_ids": { - "description": "The segment IDs that you are sending this list to. You can have both segment IDs and list IDs. Segments are limited to 10 segment IDs.", - "items": { - "type": "integer" - }, - "nullable": true, - "type": "array" - }, - "categories": { - "description": "The categories you would like associated to this campaign.", - "items": { - "type": "string" - }, - "nullable": true, - "type": "array" - }, - "suppression_group_id": { - "description": "The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type.", - "nullable": true, - "type": "integer" - }, - "custom_unsubscribe_url": { - "description": "This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups.", - "nullable": true, - "type": "string" - }, - "ip_pool": { - "description": "The pool of IPs that you would like to send this email from.", - "nullable": true, - "type": "string" - }, - "html_content": { - "description": "The HTML of your marketing email.", - "nullable": true, - "type": "string" - }, - "plain_content": { - "description": "The plain text content of your emails.", - "nullable": true, - "type": "string" - }, - "editor": { - "type": "string", - "enum": ["code", "design"], - "description": "The editor used in the UI." - } - }, - "required": ["title"], - "example": { - "id": 986724, - "title": "May Newsletter", - "subject": "New Products for Summer!", - "sender_id": 124451, - "list_ids": [110, 124], - "segment_ids": [110], - "categories": ["summer line"], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our summer line!

", - "plain_content": "Check out our summer line!", - "status": "Draft" - }, - "x-stoplight": { - "id": "campaign_request", - "name": "Campaigns Request", - "public": true - } - }, - "subuser_stats": { - "title": "subuser_stats", - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date the statistics were gathered." - }, - "stats": { - "type": "array", - "description": "The list of statistics.", - "items": { - "type": "object", - "properties": { - "first_name": { - "type": "string", - "description": "The first name of the subuser." - }, - "last_name": { - "type": "string", - "description": "The last name of the subuser." - }, - "metrics": { - "type": "object", - "properties": { - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounce_drops": { - "type": "integer", - "description": "The number of emails that were dropped because of a bounce." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "deferred": { - "type": "integer", - "description": "The number of emails that temporarily could not be delivered." - }, - "delivered": { - "type": "integer", - "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." - }, - "invalid_emails": { - "type": "integer", - "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "processed": { - "type": "integer", - "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." - }, - "requests": { - "type": "integer", - "description": "The number of emails that were requested to be delivered." - }, - "spam_report_drops": { - "type": "integer", - "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." - }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - }, - "unsubscribe_drops": { - "type": "integer", - "description": "The number of emails dropped due to a recipient unsubscribing from your emails." - }, - "unsubscribes": { - "type": "integer", - "description": "The number of recipients who unsubscribed from your emails." - } - } - }, - "name": { - "type": "string", - "description": "The username of the subuser." - }, - "type": { - "type": "string", - "description": "The type of account." - } - } - } - } - }, - "example": { - "date": "2016-02-01", - "stats": [ - { - "first_name": "John", - "last_name": "Doe", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 5, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 10, - "processed": 10, - "requests": 10, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "user1", - "type": "subuser" - } - ] - }, - "x-stoplight": { - "id": "subuser_stats", - "name": "subuser_stats", - "public": true - } - }, - "user_scheduled_send_status": { - "title": "User Scheduled Send status", - "allOf": [ - { - "$ref": "#/components/schemas/mail_batch_id" - }, - { - "type": "object", - "description": "The status of the scheduled send.", - "properties": { - "status": { - "type": "string", - "description": "The status of the scheduled send.", - "enum": ["cancel", "pause"] - } - }, - "required": ["status"] - } - ], - "example": { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", - "status": "pause" - }, - "x-stoplight": { - "id": "user_scheduled_send_status", - "name": "User Scheduled Send status", - "public": true - } - }, - "advanced_stats_clicks_opens": { - "title": "Stats: Advanced Stats with Clicks and Opens", - "description": "The individual events and their stats.", - "allOf": [ - { - "$ref": "#/components/schemas/advanced_stats_clicks" - }, - { - "$ref": "#/components/schemas/advanced_stats_opens" - } - ], - "x-stoplight": { - "id": "advanced_stats_clicks_opens", - "name": "Stats: Advanced Stats with Clicks and Opens", - "public": true - } - }, - "contactdb_segments_with_id": { - "title": "ContactDB:: Segments with ID", - "allOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the segment." - } - }, - "required": ["id"] - }, - { - "$ref": "#/components/schemas/contactdb_segments" - } - ], - "x-stoplight": { - "id": "contactdb_segments_with_id", - "name": "ContactDB:: Segments with ID", - "public": true - } - }, - "advanced_stats_clicks": { - "title": "Stats: Advanced Stats with Clicks", - "type": "object", - "description": "The individual events and their stats.", - "properties": { - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - } - }, - "x-stoplight": { - "id": "advanced_stats_clicks", - "name": "Stats: Advanced Stats with Clicks", - "public": true - } - }, - "contactdb_recipient": { - "title": "ContactDB: Recipient", - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of this recipient." - }, - "created_at": { - "type": "number", - "description": "The time this record was created in your contactdb, in unixtime." - }, - "custom_fields": { - "type": "array", - "description": "The custom fields assigned to this recipient and their values.", - "items": { - "$ref": "#/components/schemas/contactdb_custom_field_with_id_value" - } - }, - "email": { - "type": "string", - "description": "The email address of this recipient. This is a default custom field that SendGrid provides.", - "format": "email" - }, - "first_name": { - "description": "The first name of this recipient. This is a default custom field that SendGrid provides.", - "nullable": true, - "type": "string" - }, - "last_name": { - "description": "The last name of the recipient.", - "nullable": true, - "type": "string" - }, - "last_clicked": { - "description": "The last time this recipient clicked a link from one of your campaigns, in unixtime.", - "nullable": true, - "type": "number" - }, - "last_emailed": { - "description": "The last time this user was emailed by one of your campaigns, in unixtime.", - "nullable": true, - "type": "number" - }, - "last_opened": { - "description": "The last time this recipient opened an email from you, in unixtime.", - "nullable": true, - "type": "number" - }, - "updated_at": { - "type": "number", - "description": "The last update date for this recipient's record." - } - }, - "required": ["email"] - } - } - }, - "x-stoplight": { - "id": "contactdb_recipient", - "name": "ContactDB: Recipient", - "public": true - } - }, - "mail_settings_patch": { - "title": "Mail Settings: Patch", - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the mail setting is enabled." - }, - "email": { - "type": "string", - "description": "The email address of the recipient." - } - }, - "example": { - "enabled": true, - "email": "email@example.com" - }, - "x-stoplight": { - "id": "mail_settings_patch", - "name": "Mail Settings: Patch", - "public": true - } - }, - "mail_settings_forward_bounce": { - "title": "Mail Settings: Forward Bounce", - "type": "object", - "properties": { - "email": { - "description": "The email address that you would like your bounce reports forwarded to.", - "nullable": true, - "type": "string" - }, - "enabled": { - "type": "boolean", - "description": "Indicates if the bounce forwarding mail setting is enabled." - } - }, - "example": { - "enabled": false, - "email": null - }, - "x-stoplight": { - "id": "mail_settings_forward_bounce", - "name": "Mail Settings: Forward Bounce", - "public": true - } - }, - "mail_batch_id": { - "title": "Mail Batch ID", - "type": "object", - "properties": { - "batch_id": { - "type": "string", - "pattern": "^[a-zA-Z0-9\\-\\_]" - } - }, - "required": ["batch_id"], - "example": { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" - }, - "x-stoplight": { - "id": "mail_batch_id", - "name": "Mail Batch ID", - "public": true - } - }, - "subuser_post": { - "title": "Subuser::POST", - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username of the subuser." - }, - "user_id": { - "type": "number", - "description": "The user ID for this subuser." - }, - "email": { - "type": "string", - "description": "The email address for this subuser.", - "format": "email" - }, - "signup_session_token": { - "type": "string" - }, - "authorization_token": { - "type": "string" - }, - "credit_allocation": { - "type": "object", - "properties": { - "type": { - "type": "string" - } - } - } - }, - "required": ["username", "user_id", "email"], - "example": { - "username": "example_subuser", - "user_id": 1234, - "email": "example@example.com", - "signup_session_token": "", - "authorization_token": "", - "credit_allocation": { - "type": "unlimited" - } - }, - "x-stoplight": { - "id": "subuser_post", - "name": "Subuser::POST", - "public": true - } - }, - "contactdb_recipient_count": { - "title": "ContactDB: Recipient Count", - "type": "object", - "properties": { - "recipient_count": { - "type": "number", - "description": "The count of recipients." - } - }, - "required": ["recipient_count"], - "example": { - "recipient_count": 1234 - }, - "x-stoplight": { - "id": "contactdb_recipient_count", - "name": "ContactDB: Recipient Count", - "public": true - } - }, - "contactdb_custom_field_with_id_value": { - "title": "ContactDB Custom field schema.", - "allOf": [ - { - "$ref": "#/components/schemas/contactdb_custom_field_with_id" - }, - { - "type": "object", - "properties": { - "value": { - "description": "The value of this recipient's custom field", - "nullable": true, - "type": "string" - } - } - } - ], - "x-stoplight": { - "id": "contactdb_custom_field_with_id_value", - "name": "ContactDB: Custom Field with ID & Value", - "public": true - } - }, - "transactional_template_version_create": { - "title": "Transactional Templates: Version Create", - "type": "object", - "properties": { - "active": { - "type": "integer", - "description": "Set the version as the active version associated with the template (0 is inactive, 1 is active). Only one version of a template can be active. The first version created for a template will automatically be set to Active.", - "enum": [0, 1] - }, - "name": { - "type": "string", - "description": "Name of the transactional template version.", - "maxLength": 100 - }, - "html_content": { - "type": "string", - "description": "The HTML content of the version. Maximum of 1048576 bytes allowed.", - "maxLength": 1048576 - }, - "plain_content": { - "type": "string", - "description": "Text/plain content of the transactional template version. Maximum of 1048576 bytes allowed.", - "maxLength": 1048576, - "default": "" - }, - "generate_plain_content": { - "type": "boolean", - "description": "If true, plain_content is always generated from html_content. If false, plain_content is not altered.", - "default": true - }, - "subject": { - "type": "string", - "description": "Subject of the new transactional template version.", - "maxLength": 255 - }, - "editor": { - "type": "string", - "enum": ["code", "design"], - "description": "The editor used in the UI." - }, - "test_data": { - "type": "string", - "description": "For dynamic templates only, the mock json data that will be used for template preview and test sends." - } - }, - "required": ["name", "subject"], - "example": { - "template_id": "Excepteur Ut qui", - "active": 1, - "name": "pariatur non incididunt commodo", - "html_content": "dolor", - "generate_plain_content": false, - "subject": "aliquip nulla Ut", - "editor": "design", - "plain_content": "labore dolore" - }, - "x-stoplight": { - "id": "transactional_template_version_create", - "name": "Transactional Templates: Version Create", - "public": true - } - }, - "transactional-templates-version-output-lean": { - "title": "Transactional Templates: Version Output Lean", - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "ID of the transactional template version.", - "format": "uuid" - }, - "template_id": { - "type": "string", - "description": "ID of the transactional template." - }, - "active": { - "type": "integer", - "description": "Set the version as the active version associated with the template. Only one version of a template can be active. The first version created for a template will automatically be set to Active.", - "enum": [0, 1] - }, - "name": { - "type": "string", - "description": "Name of the transactional template version.", - "maxLength": 100 - }, - "subject": { - "type": "string", - "description": "Subject of the new transactional template version.", - "maxLength": 255 - }, - "updated_at": { - "type": "string", - "description": "The date and time that this transactional template version was updated." - }, - "generate_plain_content": { - "type": "boolean", - "description": "If true, plain_content is always generated from html_content. If false, plain_content is not altered.", - "default": true - }, - "editor": { - "type": "string", - "enum": ["code", "design"], - "description": "The editor used in the UI." - }, - "thumbnail_url": { - "type": "string", - "description": "A Thumbnail preview of the template's html content." - } - }, - "x-stoplight": { - "id": "transactional-templates-version-output-lean", - "name": "Transactional Templates: Version Output Lean", - "public": true - } - }, - "transactional-templates-template-lean": { - "title": "Transactional Templates: Template Lean", - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the transactional template.", - "minLength": 36, - "maxLength": 36, - "format": "uuid" - }, - "name": { - "type": "string", - "description": "The name for the transactional template.", - "maxLength": 100 - }, - "generation": { - "type": "string", - "description": "Defines the generation of the template.", - "enum": ["legacy", "dynamic"] - }, - "updated_at ": { - "type": "string", - "description": "The date and time that this transactional template version was updated.", - "pattern": "^(\\d{4}-\\d{2}-\\d{2}) ((\\d{2}):(\\d{2}):(\\d{2}))$" - }, - "versions": { - "type": "array", - "description": "The different versions of this transactional template.", - "items": { - "$ref": "#/components/schemas/transactional-templates-version-output-lean" - } - } - }, - "required": ["id", "name", "generation", "updated_at "], - "example": { - "id": "0c314114-a2b7-4523-8cbc-a293d7d19007", - "name": "example_name", - "generation": "legacy", - "updated_at ": "2021-04-28 13:12:46", - "versions": [] - }, - "x-stoplight": { - "id": "transactional-templates-template-lean", - "name": "Transactional Templates: Template Lean", - "public": true - } - }, - "custom-fields-by-id": { - "title": "custom-fields-by-id", - "type": "object", - "example": { - "w1": "2002-10-02T15:00:00Z", - "w33": 9.5, - "e2": "Coffee is a beverage that puts one to sleep when not drank." - }, - "x-stoplight": { - "id": "custom-fields-by-id", - "name": "custom-fields-by-id", - "public": true - } - }, - "custom-fields-by-name": { - "title": "custom-fields-by-name", - "type": "object", - "example": { - "birthday": "2002-10-02T15:00:00Z", - "shoe_size": 9.5, - "favoriteQuote": "Coffee is a beverage that puts one to sleep when not drank." - }, - "x-stoplight": { - "id": "custom-fields-by-name", - "name": "custom-fields-by-name", - "public": true - } - }, - "contact-details": { - "title": "contact-details", - "type": "object", - "properties": { - "address_line_1": { - "type": "string" - }, - "address_line_2": { - "type": "string" - }, - "alternate_emails": { - "type": "array", - "items": { - "type": "string" - } - }, - "city": { - "type": "string" - }, - "country": { - "type": "string" - }, - "email": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "id": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "postal_code": { - "type": "string" - }, - "state_province_region": { - "type": "string" - }, - "list_ids": { - "type": "array", - "items": { - "type": "string" - } - }, - "created_at": { - "type": "string", - "description": "The ISO8601 timestamp when the contact was created." - }, - "updated_at": { - "type": "string", - "description": "The ISO8601 timestamp when the contact was updated." - }, - "_metadata": { - "$ref": "#/components/schemas/selfmetadata" - }, - "custom_fields": { - "$ref": "#/components/schemas/custom-fields-by-name" - } - }, - "required": ["id", "list_ids", "created_at", "updated_at"], - "x-stoplight": { - "id": "contact-details", - "name": "contact-details", - "public": true - } - }, - "contact-import": { - "title": "contact-import", - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The job ID." - }, - "status": { - "type": "string", - "description": "The job state. Allowed values: `pending`, `completed`, `errored`, or `failed`." - }, - "job_type": { - "type": "string", - "description": "The job type. Allowed values: `upsert`, or `delete`." - }, - "results": { - "type": "object", - "description": "Result map of the import job.", - "properties": { - "requested_count": { - "description": "Requested contact count from the import.", - "type": "number" - }, - "created_count": { - "description": "Created contact count from the import.", - "type": "number" - }, - "updated_count": { - "description": "Updated contact count from the import.", - "type": "number" - }, - "deleted_count": { - "description": "Count of deleted contacts that resulted in error.", - "type": "number" - }, - "errored_count": { - "description": "Count of imported contacts that resulted in error.", - "type": "number" - }, - "errors_url": { - "type": "string", - "description": "The download URL of the file which provides information about any errors." - } - } - }, - "started_at": { - "description": "The ISO8601 timestamp when the job was created.", - "type": "string" - }, - "finished_at": { - "description": "The ISO8601 timestamp when the job was finished.", - "type": "string" - } - }, - "x-stoplight": { - "id": "contact-import", - "name": "contact-import", - "public": true - } - }, - "single-contact-request": { - "title": "single contact request", - "type": "object", - "properties": { - "list_ids": { - "type": "array", - "minItems": 0, - "maxItems": 100, - "description": "The contact's list IDs.", - "items": { - "type": "string", - "format": "uuid" - } - }, - "contact": { - "type": "object", - "properties": { - "primary_email": { - "type": "string" - }, - "alternate_emails": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "address_line_1": { - "type": "string" - }, - "address_line_2": { - "type": "string" - }, - "city": { - "type": "string" - }, - "state_province_region": { - "type": "string" - }, - "postal_code": { - "type": "string" - }, - "country": { - "type": "string" - }, - "custom_fields": { - "type": "object", - "properties": { - "custom_field_name1": { - "type": "string" - }, - "custom_field_name2": { - "type": "string" - } - } - } - } - } - }, - "x-stoplight": { - "id": "single-contact-request", - "name": "single contact request", - "public": true - } - }, - "contact-export": { - "title": "contact-export", - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "status": { - "type": "string", - "enum": ["pending", "ready", "failure"], - "description": "The export job's status. Allowed values: `pending`, `ready`, or `failure`." - }, - "created_at": { - "type": "string", - "description": "The ISO8601 timestamp when the export was begun." - }, - "updated_at": { - "type": "string", - "description": "The ISO8601 timestamp when the export was updated." - }, - "completed_at": { - "type": "string", - "description": "The ISO8601 timestamp when the export was completed." - }, - "expires_at": { - "type": "string", - "description": "The ISO8601 timestamp when the exported file on S3 will expire." - }, - "urls": { - "type": "array", - "description": "One or more download URLs for the contact file if the status is `ready`.", - "items": { - "type": "string" - } - }, - "message": { - "type": "string", - "description": "A human readable message if the status is `failure`." - }, - "_metadata": { - "$ref": "#/components/schemas/metadata" - }, - "contact_count": { - "type": "integer", - "description": "The total number of exported contacts." - } - }, - "required": ["id", "status", "created_at", "updated_at", "expires_at"], - "x-stoplight": { - "id": "contact-export", - "name": "contact-export", - "public": true - } - }, - "contact-summary": { - "title": "contact-summary", - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "Primary email address." - }, - "first_name": { - "type": "string" - }, - "id": { - "type": "string", - "description": "Contact UUID." - }, - "last_name": { - "type": "string" - }, - "list_ids": { - "type": "array", - "description": "List UUID linked with this contact.", - "items": { - "type": "string" - } - }, - "created_at": { - "type": "number", - "description": "Unix Epoch Timestamp." - }, - "updated_at": { - "type": "number", - "description": "Unix Epoch Timestamp." - }, - "_metadata": { - "$ref": "#/components/schemas/selfmetadata" - } - }, - "required": ["id", "list_ids", "created_at", "updated_at"], - "x-stoplight": { - "id": "contact-summary", - "name": "contact-summary", - "public": true - } - }, - "contact-request": { - "title": "contact-request", - "type": "object", - "properties": { - "address_line_1": { - "type": "string", - "description": "The first line of the address.", - "maxLength": 100 - }, - "address_line_2": { - "type": "string", - "description": "An optional second line for the address.", - "maxLength": 100 - }, - "alternate_emails": { - "type": "array", - "description": "Additional emails associated with the contact.", - "minItems": 0, - "maxItems": 5, - "items": { - "type": "string", - "maxLength": 254 - } - }, - "city": { - "type": "string", - "description": "The contact's city.", - "maxLength": 60 - }, - "country": { - "type": "string", - "description": "The contact's country. Can be a full name or an abbreviation.", - "maxLength": 50 - }, - "email": { - "type": "string", - "description": "The contact's primary email. This is required to be a valid email.", - "maxLength": 254 - }, - "first_name": { - "type": "string", - "description": "The contact's personal name.", - "maxLength": 50 - }, - "last_name": { - "type": "string", - "description": "The contact's family name.", - "maxLength": 50 - }, - "postal_code": { - "type": "string", - "description": "The contact's ZIP code or other postal code." - }, - "state_province_region": { - "type": "string", - "description": "The contact's state, province, or region.", - "maxLength": 50 - }, - "custom_fields": { - "$ref": "#/components/schemas/custom-fields-by-id" - } - }, - "required": ["email"], - "x-stoplight": { - "id": "contact-request", - "name": "contact-request", - "public": true - } - }, - "contact-details2": { - "title": "contact-details2", - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 36, - "maxLength": 36, - "format": "uuid" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "unique_name": { - "type": "string" - }, - "email": { - "type": "string", - "format": "email" - }, - "alternate_emails": { - "items": { - "type": "string", - "format": "email" - }, - "nullable": true, - "type": "array" - }, - "address_line_1": { - "type": "string" - }, - "address_line_2": { - "type": "string" - }, - "city": { - "type": "string" - }, - "state_province_region": { - "type": "string" - }, - "country": { - "type": "string" - }, - "postal_code": { - "type": "string" - }, - "phone_number": { - "type": "string" - }, - "whatsapp": { - "type": "string" - }, - "line": { - "type": "string" - }, - "facebook": { - "type": "string" - }, - "list_ids": { - "type": "array", - "items": { - "type": "string", - "format": "uuid" - } - }, - "segment_ids": { - "type": "array", - "items": { - "type": "string", - "format": "uuid" - } - }, - "custom_fields": { - "type": "object" - }, - "created_at": { - "type": "string", - "format": "date-time" - }, - "updated_at": { - "type": "string", - "format": "date-time" - }, - "_metadata": { - "$ref": "#/components/schemas/selfmetadata" - } - }, - "required": ["id", "list_ids", "created_at", "updated_at"], - "x-stoplight": { - "id": "contact-details2", - "name": "contact-details2", - "public": true - } - }, - "selfmetadata": { - "title": "selfMetadata", - "type": "object", - "properties": { - "self": { - "type": "string", - "description": "A link to this object." - } - }, - "x-stoplight": { - "id": "selfmetadata", - "name": "selfMetadata", - "public": true - } - }, - "error": { - "title": "error", - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - }, - "error_id": { - "type": "string" - }, - "parameter": { - "type": "string" - } - }, - "required": ["message"], - "x-stoplight": { - "id": "error", - "name": "error", - "public": true - } - }, - "link": { - "title": "Link", - "type": "object", - "properties": { - "rel": { - "type": "string" - }, - "href": { - "type": "string" - } - }, - "x-stoplight": { - "id": "link", - "name": "Link", - "public": true - } - }, - "metadata": { - "title": "metadata", - "type": "object", - "properties": { - "prev": { - "type": "string", - "format": "uri", - "description": "The URL of the previous page of results. If this field isn't present, you're at the start of the list." - }, - "self": { - "type": "string", - "format": "uri", - "description": "The URL of the current page of results." - }, - "next": { - "type": "string", - "format": "uri", - "description": "The URL of the next page of results. If this field isn't present, you're at the end of the list." - }, - "count": { - "type": "number", - "description": "The number of items in the entire list, i.e., across all pages." - } - }, - "x-stoplight": { - "id": "metadata", - "name": "metadata", - "public": true - } - }, - "webhook": { - "title": "webhook", - "type": "object", - "properties": { - "url": { - "type": "string", - "description": "The URL to invoke in the webhook" - }, - "nonce": { - "type": "string", - "description": "The one time nonce to use when \"signature\" is \"hmac-sha1\"", - "minLength": 8, - "maxLength": 32 - } - }, - "required": ["url", "nonce"], - "x-stoplight": { - "id": "webhook", - "name": "webhook", - "public": true - } - }, - "list": { - "title": "list", - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The generated ID for your list.", - "minLength": 36, - "maxLength": 36 - }, - "name": { - "type": "string", - "description": "The name you gave your list." - }, - "contact_count": { - "type": "integer", - "description": "The number of contacts currently stored on the list." - }, - "_metadata": { - "$ref": "#/components/schemas/selfmetadata" - } - }, - "x-stoplight": { - "id": "list", - "name": "list", - "public": true - } - }, - "reserved_field_definitions_response": { - "title": "reserved_field_definitions_response", - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "field_type": { - "type": "string", - "enum": ["Text", "Number", "Date"] - }, - "read_only": { - "type": "boolean", - "default": false, - "description": "When `true` this means API consumers are unable to set the value of this field on contacts." - } - } - }, - "required": ["name", "field_type"], - "example": [ - { - "id": "_rf20_T", - "name": "automation_id", - "field_type": "Text", - "read_only": true - } - ], - "x-stoplight": { - "id": "reserved_field_definitions_response", - "name": "reserved_field_definitions_response", - "public": true - } - }, - "custom_field_definitions_response": { - "title": "custom_field_definitions_response", - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "field_type": { - "type": "string", - "enum": ["Text", "Number", "Date"] - } - }, - "required": ["id", "name", "field_type"], - "example": { - "id": "a1_D", - "name": "custom_field_name", - "field_type": "Date" - }, - "x-stoplight": { - "id": "custom_field_definitions_response", - "name": "custom_field_definitions_response", - "public": true - } - }, - "segment_write": { - "title": "segment_write", - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "query_dsl": { - "type": "string", - "description": "Use this field for adding your query string." - } - }, - "required": ["name", "query_dsl"], - "x-stoplight": { - "id": "segment_write", - "name": "segment_write", - "public": true - } - }, - "segment_summary": { - "title": "segment_summary", - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 36, - "maxLength": 36, - "format": "uuid" - }, - "contacts_count": { - "type": "integer" - }, - "created_at": { - "type": "string", - "description": "ISO8601 of created timestamp\n", - "format": "date-time" - }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "parent_list_id": { - "type": "string", - "minLength": 36, - "maxLength": 36, - "format": "uuid", - "description": "The id of the list if this segment is a child of a list. This implies the query `AND CONTAINS(list_ids, ${parent_list_id})`" - }, - "sample_updated_at": { - "type": "string", - "description": "ISO8601 timestamp the sample was last updated", - "format": "date-time" - }, - "updated_at": { - "type": "string", - "description": "ISO8601 timestamp the object was last updated", - "format": "date-time" - }, - "next_sample_update": { - "type": "string", - "description": "ISO8601 string that is equal to `sample_updated_at` plus an internally calculated offset that depends on how often contacts enter or exit segments as the scheduled pipeline updates the samples." - } - }, - "required": ["id", "contacts_count", "created_at", "sample_updated_at", "updated_at"], - "x-stoplight": { - "id": "segment_summary", - "name": "segment_summary", - "public": true - } - }, - "segment_query_json": { - "title": "segment_query_json", - "type": "object", - "properties": { - "contacts": { - "type": "object", - "properties": { - "op": { - "type": "string" - }, - "l": { - "type": "object", - "properties": { - "op": { - "type": "string" - }, - "l": { - "type": "object", - "properties": { - "op": { - "type": "string" - }, - "l": { - "type": "object", - "properties": { - "v": { - "type": "string" - }, - "t": { - "type": "string" - } - } - }, - "r": { - "type": "object", - "properties": { - "v": { - "type": "string" - }, - "t": { - "type": "string" - } - } - } - } - }, - "r": { - "type": "object", - "properties": { - "op": { - "type": "string" - }, - "l": { - "type": "object", - "properties": { - "v": { - "type": "string" - }, - "t": { - "type": "string" - }, - "args": { - "type": "array", - "items": { - "type": "object", - "properties": { - "v": { - "type": "string" - }, - "t": { - "type": "string" - } - } - } - } - } - }, - "r": { - "type": "object", - "properties": { - "v": { - "type": "string" - }, - "t": { - "type": "string" - } - } - } - } - } - } - }, - "r": { - "type": "object", - "properties": { - "op": { - "type": "string" - }, - "l": { - "type": "object", - "properties": { - "v": { - "type": "string" - }, - "t": { - "type": "string" - } - } - }, - "r": { - "type": "object", - "properties": { - "v": { - "type": "array", - "items": { - "type": "string" - } - }, - "t": { - "type": "string" - } - } - } - } - } - } - } - }, - "x-stoplight": { - "id": "segment_query_json", - "name": "segment_query_json", - "public": true - } - }, - "contact_response": { - "title": "contact_response", - "type": "object", - "properties": { - "id": { - "type": "string", - "maxLength": 36, - "pattern": "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}", - "format": "uuid", - "description": "ID assigned to a contact when added to the system." - }, - "email": { - "type": "string", - "minLength": 3, - "maxLength": 254, - "format": "email", - "description": "Email of the contact. This is a reserved field." - }, - "alternate_emails": { - "type": "array", - "uniqueItems": true, - "minItems": 0, - "description": "Alternate emails of the contact. This is a reserved field.", - "items": { - "type": "string", - "minLength": 3, - "maxLength": 254, - "format": "email" - } - }, - "first_name": { - "type": "string", - "minLength": 1, - "description": "First name of the contact. This is a reserved field." - }, - "last_name": { - "type": "string", - "minLength": 1, - "description": "Last name of the contact. This is a reserved field." - }, - "address_line_1": { - "type": "string", - "minLength": 0, - "description": "First line of address of the contact. This is a reserved field." - }, - "address_line_2": { - "type": "string", - "minLength": 0, - "description": "Second line of address of the contact. This is a reserved field." - }, - "city": { - "type": "string", - "minLength": 0, - "pattern": "^[a-zA-Z\\u0080-\\u024F\\s\\/\\-\\)\\(\\`\\.\\\"\\']+$", - "description": "City associated with the contact. This is a reserved field." - }, - "state_province_region": { - "type": "string", - "minLength": 0, - "description": "State associated with the contact. This is a reserved field." - }, - "postal_code": { - "type": "integer", - "description": "Zipcode associated with the address of the contact. This is a reserved field." - }, - "country": { - "type": "string", - "minLength": 0, - "description": "Country associated with the address of the contact. This is a reserved field." - }, - "list_ids": { - "type": "array", - "uniqueItems": true, - "description": "IDs of all lists the contact is part of", - "items": { - "type": "string", - "format": "uuid" - } - }, - "custom_fields": { - "type": "object", - "minProperties": 0, - "description": "The user may choose to create up to 120 custom fields or none at all. This is not a reserved field.", - "properties": { - "custom_field_name1": { - "type": "string", - "minLength": 0 - }, - "custom_field_name2": { - "type": "string", - "minLength": 0 - }, - "": { - "type": "string" - } - } - }, - "segment_ids": { - "type": "array", - "uniqueItems": true, - "description": "IDs of all segments the contact is part of", - "items": { - "type": "string", - "format": "uuid" - } - } - }, - "required": [ - "id", - "email", - "alternate_emails", - "first_name", - "last_name", - "address_line_1", - "address_line_2", - "city", - "state_province_region", - "postal_code", - "country", - "custom_fields" - ], - "example": { - "id": "47d23ab0-d895-4359-a0d1-ffc7a6fc7e70", - "email": "abcd@gmail.com", - "alternate_emails": ["abcd@yahoo.com", "abcd@hotmail.com"], - "first_name": "Ab", - "last_name": "Cd", - "address_line_1": "street address / P.O. box / CompanyName / c/o", - "address_line_2": "apartment, suite, unit, building, floor etc", - "city": "Redwood City", - "state_province_region": "CA", - "postal_code": 94063, - "country": "USA", - "custom_fields": { - "custom_field_name1": "custom_field_value1", - "custom_field_name2": "custom_field_value2" - } - }, - "x-stoplight": { - "id": "contact_response", - "name": "contact_response", - "public": true - } - }, - "TNE-senderID": { - "title": "Sender ID Response Body", - "allOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The unique identifier of the sender." - } - } - }, - { - "$ref": "#/components/schemas/senders-id-request-body" - }, - { - "type": "object", - "properties": { - "verified": { - "type": "object", - "description": "Only verified sender identities can be used to send email.", - "properties": { - "status": { - "type": "boolean", - "description": "Whether the sender identity has been verified. Only verified sender identities can be used to send email." - }, - "reason": { - "description": "The reason for a verification failure, or null if verification succeeeded or has yet to take place.", - "nullable": true, - "type": "string" - } - } - }, - "updated_at": { - "type": "integer", - "description": "The time the sender identity was last updated." - }, - "created_at": { - "type": "integer", - "description": "The time the sender identity was created." - }, - "locked": { - "type": "boolean", - "description": "A sender identity is locked when it is associated with a campaign in the Draft, Scheduled, or In Progress state. You can't update or delete a locked sender identity." - } - } - } - ], - "x-stoplight": { - "id": "TNE-senderID", - "name": "Sender ID Response Body", - "public": true - } - }, - "api-error": { - "title": "error", - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - }, - "error_id": { - "type": "string" - } - }, - "required": ["message", "field", "error_id"], - "x-stoplight": { - "id": "api-error", - "name": "error", - "public": true - } - }, - "api-errors": { - "title": "errors", - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "$ref": "#/components/schemas/api-error" - } - } - }, - "x-stoplight": { - "id": "api-errors", - "name": "errors", - "public": true - } - }, - "_metadata": { - "title": "_metadata", - "type": "object", - "properties": { - "prev": { - "type": "string", - "format": "uri" - }, - "self": { - "type": "string", - "format": "uri" - }, - "next": { - "type": "string", - "format": "uri" - }, - "count": { - "type": "integer", - "minimum": 0 - } - }, - "x-stoplight": { - "id": "_metadata", - "name": "_metadata", - "public": true - } - }, - "design-input": { - "title": "Design Input", - "allOf": [ - { - "$ref": "#/components/schemas/design-duplicate-input" - }, - { - "$ref": "#/components/schemas/design-common-fields" - }, - { - "type": "object", - "properties": { - "html_content": { - "type": "string", - "description": "The HTML content of the Design.", - "maxLength": 1048576 - }, - "plain_content": { - "type": "string", - "description": "Plain text content of the Design.", - "maxLength": 1048576, - "default": "" - } - }, - "required": ["html_content"] - } - ], - "example": { - "name": "Ahoy, World!", - "editor": "design", - "subject": "Getting Started", - "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", - "plain_content": "Ahoy, World!\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )" - }, - "x-stoplight": { - "id": "design-input", - "name": "Design Input", - "public": true - } - }, - "design-output": { - "title": "Design Output", - "allOf": [ - { - "$ref": "#/components/schemas/design-output-summary" - }, - { - "$ref": "#/components/schemas/design-input" - } - ], - "x-stoplight": { - "id": "design-output", - "name": "Design Output", - "public": true - } - }, - "design-output-summary": { - "title": "Design Output - Summary", - "allOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "ID of the Design.", - "format": "uuid" - }, - "updated_at": { - "type": "string", - "description": "Datetime that Design was last updated.", - "format": "ISO 8601 date-time" - }, - "created_at": { - "type": "string", - "description": "Datetime that Design was created.", - "format": "ISO 8601 date-time" - }, - "thumbnail_url": { - "type": "string", - "description": "A Thumbnail preview of the template's html content." - } - } - }, - { - "$ref": "#/components/schemas/design-duplicate-input" - }, - { - "$ref": "#/components/schemas/design-common-fields" - } - ], - "example": { - "result": [ - { - "id": "3247eaea-c912-42a3-b0bc-60bdaf210396", - "name": "Welcome Email", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/llny8o5b3m636z92p7hbjnmq1jvpka39p370jwtin2s1wxv7x1sgm0y5fk518d0s.png", - "subject": "Welcom to the Cake or Pie Cafe", - "created_at": "2021-04-09T17:29:46Z", - "updated_at": "2021-04-09T17:29:55Z", - "editor": "code", - "categories": ["welcome", "new customer"] - }, - { - "id": "02dfd792-f31f-439a-a79e-5c47fbcfdbac", - "name": "Monthly Promo", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/hfyxahd7ues2ajuoeoqq2xe6ibdasl1q89ox0y9ncya2ftpoicssmtf9ddus4c39.png", - "subject": "Free Dozen Cupcakes", - "created_at": "2021-04-09T17:29:21Z", - "updated_at": "2021-04-09T17:29:42Z", - "editor": "design", - "categories": ["promo", "coupon"] - }, - { - "id": "e54be823-19ef-4c6f-8b60-efd7514f492d", - "name": "Duplicate: Ingrid & Anders", - "generate_plain_content": true, - "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/12kni9gjpyb9uxmwr9vk7unycjr70u95zoyhe9sg2zounul2zg7dih1s20k13q2z.png", - "subject": "Welcome to Ingrid & Anders!", - "created_at": "2020-10-09T17:33:46Z", - "updated_at": "2021-04-07T19:57:52Z", - "editor": "design", - "categories": [] - } - ], - "_metadata": { - "self": "https://api.sendgrid.com/v3/designs?page_token=vHdvHCg0w1F-TmWJcPNpTEnFY2aPEmRBHONwOgZ6TgJbX2_I", - "count": 3 - } - }, - "x-stoplight": { - "id": "design-output-summary", - "name": "Design Output - Summary", - "public": true - } - }, - "design-duplicate-input": { - "title": "Design Duplicate Design Input", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the new design.", - "default": "Duplicate: " - }, - "editor": { - "type": "string", - "description": "The editor used in the UI.", - "enum": ["code", "design"] - } - }, - "example": { - "name": "Ahoy, Cake or Pie Cafe!", - "editor": "design" - }, - "x-stoplight": { - "id": "design-duplicate-input", - "name": "Design Duplicate Design Input", - "public": true - } - }, - "contact-details3": { - "title": "contact-details3", - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "unique_name": { - "type": "string" - }, - "email": { - "type": "string" - }, - "alternate_emails": { - "type": "array", - "items": { - "type": "string" - } - }, - "address_line_1": { - "type": "string" - }, - "address_line_2": { - "type": "string" - }, - "city": { - "type": "string" - }, - "state_province_region": { - "type": "string" - }, - "country": { - "type": "string" - }, - "postal_code": { - "type": "string" - }, - "phone_number": { - "type": "string" - }, - "whatsapp": { - "type": "string" - }, - "line": { - "type": "string" - }, - "facebook": { - "type": "string" - }, - "list_ids": { - "type": "array", - "items": { - "type": "string" - } - }, - "segment_ids": { - "type": "array", - "items": { - "type": "string" - } - }, - "custom_fields": { - "type": "object" - }, - "created_at": { - "type": "string" - }, - "updated_at": { - "type": "string" - }, - "_metadata": { - "$ref": "#/components/schemas/selfmetadata" - } - }, - "required": ["id", "list_ids", "segment_ids", "created_at", "updated_at"], - "x-stoplight": { - "id": "contact-details3", - "name": "contact-details3", - "public": true - } - }, - "transactional-template-warning": { - "title": "Warning", - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "Warning message for the user" - } - }, - "example": { - "message": "A sample warning message." - }, - "x-stoplight": { - "id": "transactional-template-warning", - "name": "Warning", - "public": true - } - }, - "errors": { - "title": "Errors", - "type": "object", - "description": "If the request is incorrect, an array of errors will be returned.", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "parameter": { - "type": "string", - "description": "The parameter in the request body that is incorrect." - }, - "message": { - "description": "A description of what is wrong with the field passed in the request.", - "nullable": true, - "type": "string" - }, - "field": { - "nullable": true, - "type": "string" - } - }, - "required": ["parameter", "message"] - } - } - }, - "required": ["errors"], - "x-stoplight": { - "id": "errors", - "name": "errors", - "public": true - } - }, - "singlesends-response": { - "title": "singlesends-response", - "type": "object", - "properties": { - "results": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "This is the ID of the Single Dend you require stats for.", - "format": "uuid" - }, - "ab_variation": { - "type": "string", - "default": "a14dcc63-d651-4c57-9826-4a3705f5c78d", - "description": "This is the A/B variation of the Single Send stat returned. If the `group_by` parameter doesn't include `ab_variation` in the request, then the value is \"all\".", - "format": "uuid" - }, - "ab_phase": { - "type": "string", - "default": "all", - "description": "This is the A/B phase of the Single Send stat returned. If the `group_by` parameter doesn't include `ab_phase` in the request, then the value is \"all\".", - "enum": ["send", "test", "all"] - }, - "aggregation": { - "type": "string", - "description": "This describes the time unit to which the stat is rolled up. It is based on the `aggregated_by` parameter included in the request. It can be \"total\" or the date (in YYYY-MM-DD format) the stats are for.", - "default": "total" - }, - "stats": { - "$ref": "#/components/schemas/metrics" - } - }, - "required": ["id", "ab_variation", "ab_phase"] - } - }, - "_metadata": { - "$ref": "#/components/schemas/metadata" - } - }, - "required": ["results", "_metadata"], - "x-stoplight": { - "id": "singlesends-response", - "name": "singlesends-response", - "public": true - } - }, - "automations-response": { - "title": "automations-response", - "type": "object", - "properties": { - "results": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "This is the ID of the Automation you are requesting stats for.", - "format": "uuid" - }, - "aggregation": { - "type": "string", - "description": "This describes the time unit to which the stat is rolled up. It is based on the `aggregated_by` parameter included in the request. It can be \"total\" or the date (in YYYY-MM-DD format) the stats are for.", - "default": "total" - }, - "step_id": { - "type": "string", - "description": "This is the ID of the step if the stats were requested to be grouped by `step_id`.", - "default": "all" - }, - "stats": { - "$ref": "#/components/schemas/metrics" - } - }, - "required": ["id", "aggregation", "step_id"] - } - }, - "_metadata": { - "$ref": "#/components/schemas/metadata" - } - }, - "required": ["results"], - "x-stoplight": { - "id": "automations-response", - "name": "automations-response", - "public": true - } - }, - "metrics": { - "title": "metrics", - "type": "object", - "properties": { - "bounce_drops": { - "type": "integer" - }, - "bounces": { - "type": "integer" - }, - "clicks": { - "type": "integer" - }, - "delivered": { - "type": "integer" - }, - "invalid_emails": { - "type": "integer" - }, - "opens": { - "type": "integer" - }, - "requests": { - "type": "integer" - }, - "spam_report_drops": { - "type": "integer" - }, - "spam_reports": { - "type": "integer" - }, - "unique_clicks": { - "type": "integer" - }, - "unique_opens": { - "type": "integer" - }, - "unsubscribes": { - "type": "integer" - } - }, - "required": [ - "bounce_drops", - "bounces", - "clicks", - "delivered", - "invalid_emails", - "opens", - "requests", - "spam_report_drops", - "spam_reports", - "unique_clicks", - "unique_opens", - "unsubscribes" - ], - "x-stoplight": { - "id": "metrics", - "name": "metrics", - "public": true - } - }, - "singlesend_search": { - "title": "singlesend_search", - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100, - "description": "leading and trailing wildcard search on name of the Single Send" - }, - "status": { - "type": "array", - "description": "current status of the Single Send", - "uniqueItems": true, - "items": { - "type": "string", - "enum": ["draft", "scheduled", "triggered"] - } - }, - "categories": { - "type": "array", - "description": "categories to associate with this Single Send, match any single send that has at least one of the categories", - "uniqueItems": true, - "items": { - "type": "string" - } - } - }, - "x-stoplight": { - "id": "singlesend_search", - "name": "singlesend_search", - "public": true - } - }, - "singlesend_request": { - "title": "singlesend_request", - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100, - "description": "The name of the Single Send." - }, - "categories": { - "type": "array", - "uniqueItems": true, - "maxItems": 10, - "description": "The categories to associate with this Single Send.", - "items": { - "type": "string" - } - }, - "send_at": { - "type": "string", - "format": "date-time", - "description": "The ISO 8601 time at which to send the Single Send — this must be set for a future time." - }, - "send_to": { - "type": "object", - "properties": { - "list_ids": { - "type": "array", - "description": "The recipient List IDs that will receive the Single Send.", - "maxItems": 10, - "items": { - "type": "string", - "format": "uuid" - } - }, - "segment_ids": { - "type": "array", - "description": "The recipient Segment IDs that will receive the Single Send.", - "maxItems": 10, - "items": { - "type": "string", - "format": "uuid" - } - }, - "all": { - "type": "boolean", - "description": "Set to `true` to send to All Contacts. If set to `false`, at least one `list_ids` or `segment_ids` value must be provided before the Single Send is scheduled to be sent to recipients.", - "default": false - } - } - }, - "email_config": { - "type": "object", - "properties": { - "subject": { - "type": "string", - "description": "The subject line of the Single Send. Do not include this field when using a `design_id`." - }, - "html_content": { - "type": "string", - "description": "The HTML content of the Single Send. Do not include this field when using a `design_id`." - }, - "plain_content": { - "type": "string", - "description": "The plain text content of the Single Send. Do not include this field when using a `design_id`." - }, - "generate_plain_content": { - "type": "boolean", - "description": "If set to `true`, `plain_content` is always generated from `html_content`. If set to false, `plain_content` is not altered.", - "default": true - }, - "design_id": { - "type": "string", - "description": "A `design_id` can be used in place of `html_content`, `plain_content`, and/or `subject`. You can retrieve a design's ID from the [\"List Designs\" endpoint](https://sendgrid.api-docs.io/v3.0/designs-api/list-designs) or by pulling it from the design's detail page URL in the Marketing Campaigns App." - }, - "editor": { - "type": "string", - "enum": ["code", "design"], - "description": "The editor — `\"design\"` or `\"code\"` — used to modify the Single Send's design in the Marketing Campaigns App.", - "default": "code" - }, - "suppression_group_id": { - "description": "The ID of the Suppression Group to allow recipients to unsubscribe — you must provide this or the `custom_unsubscribe_url`.", - "nullable": true, - "type": "integer" - }, - "custom_unsubscribe_url": { - "description": "The URL allowing recipients to unsubscribe — you must provide this or the `suppression_group_id`.", - "format": "uri", - "nullable": true, - "type": "string" - }, - "sender_id": { - "description": "The ID of the verified Sender. You can retrieve a verified Sender's ID from the [\"Get Verified Senders\" endpoint](https://sendgrid.api-docs.io/v3.0/sender-verification/get-verified-senders) or by pulling it from the Sender's detail page URL in the SendGrid App.", - "nullable": true, - "type": "integer" - }, - "ip_pool": { - "description": "The name of the IP Pool from which the Single Send emails are sent.", - "nullable": true, - "type": "string" - } - } - } - }, - "required": ["name"], - "x-stoplight": { - "id": "singlesend_request", - "name": "singlesend_request", - "public": true - } - }, - "singlesend_schedule": { - "title": "singlesend-schedule", - "type": "object", - "properties": { - "send_at": { - "type": "string", - "format": "date-time", - "description": "This is the ISO 8601 time at which to send the Single Send; must be in future, or the string \"now\"" - }, - "status": { - "type": "string", - "enum": ["draft", "scheduled", "triggered"] - } - }, - "required": ["send_at"], - "x-stoplight": { - "id": "singlesend_schedule", - "name": "singlesend-schedule", - "public": true - } - }, - "singlesend_warning": { - "title": "singlesend_warning", - "type": "object", - "properties": { - "warnings": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - }, - "warning_id": { - "type": "string" - } - } - } - } - }, - "x-stoplight": { - "id": "singlesend_warning", - "name": "singlesend_warning", - "public": true - } - }, - "to_email_array": { - "title": "To Email Array", - "type": "array", - "items": { - "type": "object", - "properties": { - "email": { - "type": "string", - "format": "email", - "description": "The intended recipient's email address." - }, - "name": { - "type": "string", - "description": "The intended recipient's name." - } - }, - "required": ["email"] - }, - "example": [ - { - "email": "john_doe@example.com", - "name": "John Doe" - } - ], - "x-stoplight": { - "id": "to_email_array", - "name": "To Email Array", - "public": true - } - }, - "event-webhook-update-oauth-request": { - "title": "Webhooks: Event Webhook Update with OAuth Request", - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the event webhook is enabled." - }, - "url": { - "type": "string", - "description": "The URL that you want the event webhook to POST to." - }, - "group_resubscribe": { - "type": "boolean", - "description": "Recipient resubscribes to specific group by updating preferences. You need to enable Subscription Tracking for getting this type of event." - }, - "delivered": { - "type": "boolean", - "description": "Message has been successfully delivered to the receiving server." - }, - "group_unsubscribe": { - "type": "boolean", - "description": "Recipient unsubscribe from specific group, by either direct link or updating preferences. You need to enable Subscription Tracking for getting this type of event." - }, - "spam_report": { - "type": "boolean", - "description": "Recipient marked a message as spam." - }, - "bounce": { - "type": "boolean", - "description": "Receiving server could not or would not accept message." - }, - "deferred": { - "type": "boolean", - "description": "Recipient's email server temporarily rejected message." - }, - "unsubscribe": { - "type": "boolean", - "description": "Recipient clicked on message's subscription management link. You need to enable Subscription Tracking for getting this type of event." - }, - "processed": { - "type": "boolean", - "description": "Message has been received and is ready to be delivered." - }, - "open": { - "type": "boolean", - "description": "Recipient has opened the HTML message. You need to enable Open Tracking for getting this type of event." - }, - "click": { - "type": "boolean", - "description": "Recipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event." - }, - "dropped": { - "type": "boolean", - "description": "You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota" - }, - "oauth_client_id": { - "type": "string", - "description": "The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token. When passing data in this field, you must also include the oauth_token_url field." - }, - "oauth_client_secret": { - "type": "string", - "description": "This secret is needed only once to create an access token. SendGrid will store this secret, allowing you to update your Client ID and Token URL without passing the secret to SendGrid again. When passing data in this field, you must also include the oauth_client_id and oauth_token_url fields." - }, - "oauth_token_url": { - "type": "string", - "description": "The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider. When passing data in this field, you must also include the oauth_client_id field." - } - }, - "required": [ - "enabled", - "url", - "group_resubscribe", - "delivered", - "group_unsubscribe", - "spam_report", - "bounce", - "deferred", - "unsubscribe", - "processed", - "open", - "click", - "dropped" - ], - "x-stoplight": { - "id": "event-webhook-update-oauth-request", - "name": "Webhooks: Event Webhook Update with OAuth Request", - "public": true - } - }, - "webhooks-event-webhook-request": { - "title": "Webhooks: Event Webhook Request", - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the event webhook is enabled." - }, - "url": { - "type": "string", - "description": "The URL that you want the event webhook to POST to." - }, - "group_resubscribe": { - "type": "boolean", - "description": "Recipient resubscribes to specific group by updating preferences. You need to enable Subscription Tracking for getting this type of event." - }, - "delivered": { - "type": "boolean", - "description": "Message has been successfully delivered to the receiving server." - }, - "group_unsubscribe": { - "type": "boolean", - "description": "Recipient unsubscribe from specific group, by either direct link or updating preferences. You need to enable Subscription Tracking for getting this type of event." - }, - "spam_report": { - "type": "boolean", - "description": "Recipient marked a message as spam." - }, - "bounce": { - "type": "boolean", - "description": "Receiving server could not or would not accept message." - }, - "deferred": { - "type": "boolean", - "description": "Recipient's email server temporarily rejected message." - }, - "unsubscribe": { - "type": "boolean", - "description": "Recipient clicked on message's subscription management link. You need to enable Subscription Tracking for getting this type of event." - }, - "processed": { - "type": "boolean", - "description": "Message has been received and is ready to be delivered." - }, - "open": { - "type": "boolean", - "description": "Recipient has opened the HTML message. You need to enable Open Tracking for getting this type of event." - }, - "click": { - "type": "boolean", - "description": "Recipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event." - }, - "dropped": { - "type": "boolean", - "description": "You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota" - }, - "oauth_client_id": { - "type": "string", - "description": "The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token. When passing data in this field, you must also include the oauth_token_url field." - }, - "oauth_token_url": { - "type": "string", - "description": "The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider. When passing data in this field, you must also include the oauth_client_id field." - } - }, - "required": [ - "enabled", - "url", - "group_resubscribe", - "delivered", - "group_unsubscribe", - "spam_report", - "bounce", - "deferred", - "unsubscribe", - "processed", - "open", - "click", - "dropped" - ], - "x-stoplight": { - "id": "webhooks-event-webhook-request", - "name": "Webhooks: Event Webhook Request", - "public": true - } - }, - "reply_to_email_object": { - "title": "Reply_to Email Object", - "type": "object", - "properties": { - "email": { - "type": "string", - "format": "email", - "description": "The email address where any replies or bounces will be returned." - }, - "name": { - "type": "string", - "description": "A name or title associated with the `reply_to` email address." - } - }, - "required": ["email"], - "example": { - "email": "jane_doe@example.com", - "name": "Jane Doe" - }, - "x-stoplight": { - "id": "reply_to_email_object", - "name": "Reply_to Email Object", - "public": true - } - }, - "automations-link-stats-response": { - "title": "automations-link-stats-response", - "type": "object", - "properties": { - "results": { - "type": "array", - "description": "", - "items": { - "type": "object", - "properties": { - "url": { - "type": "string", - "description": "This is the URL of the link clicked. If `{{custom_fields}}` are part of the URL, they will be included.", - "format": "uri" - }, - "url_location": { - "type": "integer", - "description": "This is the location of the link clicked in each Automation step. Links are located according to their position within the message; the topmost link has index `0`.", - "minimum": 0 - }, - "step_id": { - "type": "string", - "description": "This is the ID of the step if the stats were requested to be grouped by `step_id`.", - "format": "uuid" - }, - "clicks": { - "type": "integer", - "minimum": 1, - "description": "The number of clicks on this particular link." - } - }, - "required": ["url", "step_id", "clicks"] - } - }, - "total_clicks": { - "type": "integer" - }, - "_metadata": { - "$ref": "#/components/schemas/link-tracking-metadata" - } - }, - "required": ["results", "total_clicks", "_metadata"], - "x-stoplight": { - "id": "automations-link-stats-response", - "name": "automations-link-stats-response", - "public": true - } - }, - "link-tracking-metadata": { - "title": "link tracking metadata", - "type": "object", - "properties": { - "prev": { - "type": "string", - "format": "uri", - "description": "The URL of the previous page of results. If this field isn't present, you're at the start of the list." - }, - "self": { - "type": "string", - "format": "uri", - "description": "The URL of the current page of results." - }, - "next": { - "type": "string", - "format": "uri", - "description": "The URL of the next page of results. If this field isn't present, you're at the end of the list." - }, - "count": { - "type": "number", - "description": "The number of items in the entire list, i.e., across all pages." - } - }, - "x-stoplight": { - "id": "link-tracking-metadata", - "name": "link tracking metadata", - "public": true - } - }, - "singlesends-link-stats-response": { - "title": "singlesends-link-stats-response", - "type": "object", - "properties": { - "results": { - "type": "array", - "description": "This is the index of the link's location in the email contents.", - "items": { - "type": "object", - "properties": { - "url": { - "type": "string", - "description": "This is the URL of the link clicked. If `{{custom_fields}}` are part of the URL, they will be included.", - "format": "uri" - }, - "url_location": { - "type": "integer", - "description": "This is the location of the link clicked in each Single Send A/B variation, or in the Single Send itself if there are no variations. Links are numbered from the top down; the topmost link is index `0`.", - "minimum": 0 - }, - "ab_variation": { - "type": "string", - "description": "This is the A/B variation of the Single Send stat returned. It is set to `\"all\"` if the `ab_variation` query parameter was not set in the request and `group_by` doesn't contain `ab_variation`.", - "format": "uuid" - }, - "ab_phase": { - "type": "string", - "description": "This is the A/B phase of the Single Send stat returned. If the `ab_phase` query parameter was not provided, it will return `\"all\"`.", - "enum": ["send", "test", "all"] - }, - "clicks": { - "type": "integer", - "minimum": 1, - "description": "the number of clicks on this particular link" - } - }, - "required": ["url", "ab_variation", "ab_phase", "clicks"] - } - }, - "_metadata": { - "$ref": "#/components/schemas/link-tracking-metadata" - }, - "total_clicks": { - "type": "integer" - } - }, - "required": ["results", "_metadata"], - "x-stoplight": { - "id": "singlesends-link-stats-response", - "name": "singlesends-link-stats-response", - "public": true - } - }, - "domain-authentication-200-response": { - "title": "Domain Authentication 200 Response", - "type": "array", - "items": { - "allOf": [ - { - "$ref": "#/components/schemas/authentication_domain" - }, - { - "type": "object", - "properties": { - "subusers": { - "type": "array", - "items": { - "type": "object", - "properties": { - "user_id": { - "type": "integer", - "description": "The ID of the subuser that this authenticated domain will be associated with." - }, - "username": { - "type": "string", - "description": "The username of the subuser that this authenticated domain is associated with." - } - } - } - }, - "last_validation_attempt_at": { - "type": "integer", - "description": "A Unix epoch timestamp representing the last time of a validation attempt." - } - } - } - ] - }, - "example": [ - { - "id": 1, - "user_id": 7, - "subdomain": "mail", - "domain": "example.com", - "username": "jane@example.com", - "ips": ["192.168.1.1", "192.168.1.2"], - "custom_spf": true, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": true, - "dns": { - "mail_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "u7.wl.sendgrid.net" - }, - "dkim1": { - "valid": true, - "type": "cname", - "host": "s1._domainkey.example.com", - "data": "s1._domainkey.u7.wl.sendgrid.net" - }, - "dkim2": { - "valid": true, - "type": "cname", - "host": "s2._domainkey.example.com", - "data": "s2._domainkey.u7.wl.sendgrid.net" - } - } - }, - { - "id": 2, - "user_id": 8, - "subdomain": "new", - "domain": "example2.com", - "username": "john@example2.com", - "ips": [], - "custom_spf": false, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": false, - "dns": { - "mail_cname": { - "valid": false, - "type": "mx", - "host": "news.example2.com", - "data": "sendgrid.net" - }, - "dkim1": { - "valid": false, - "type": "txt", - "host": "example2.com", - "data": "k=rsa; t=s; p=publicKey" - }, - "dkim2": { - "valid": false, - "type": "txt", - "host": "example2.com", - "data": "k=rsa; t=s p=publicKey" - } - } - } - ], - "x-stoplight": { - "id": "domain-authentication-200-response", - "name": "Domain Authentication 200 Response", - "public": true - } - }, - "abtest_summary": { - "title": "abTest_summary", - "properties": { - "type": { - "type": "string", - "description": "What differs between the A/B tests", - "enum": ["subject", "content"] - }, - "winner_criteria": { - "type": "string", - "description": "How the winner will be decided", - "enum": ["open", "click", "manual"] - }, - "test_percentage": { - "type": "integer", - "description": "What percentage of your recipient will be included in your A/B testing" - }, - "duration": { - "type": "string", - "description": "How long the A/B Testing will last" - }, - "winning_template_id": { - "type": "string", - "description": "Winner of the A/B Test" - }, - "winner_selected_at": { - "description": "When the winner was selected", - "nullable": true, - "type": "string" - }, - "expiration_date": { - "description": "Last day to select an A/B Test Winner", - "nullable": true, - "type": "string" - } - }, - "required": [ - "type", - "winner_criteria", - "test_percentage", - "duration", - "winning_template_id", - "winner_selected_at", - "expiration_date" - ], - "x-stoplight": { - "id": "abtest_summary", - "name": "abTest_summary", - "public": true - }, - "nullable": true, - "type": "object" - }, - "singlesend_response_short": { - "title": "singlesend_response_short", - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100, - "description": "name of the Single Send" - }, - "abtest": { - "$ref": "#/components/schemas/abtest_summary" - }, - "status": { - "type": "string", - "enum": ["draft", "scheduled", "triggered"], - "description": "current status of the Single Send" - }, - "categories": { - "type": "array", - "uniqueItems": true, - "maxItems": 10, - "description": "categories to associate with this Single Send", - "items": { - "type": "string" - } - }, - "send_at": { - "type": "string", - "format": "date-time", - "description": "the ISO 8601 time at which to send the Single Send; must be in future" - }, - "is_abtest": { - "type": "boolean", - "description": "true if the Single Send's AB Test functionality has been toggled on" - }, - "updated_at": { - "type": "string", - "description": "the ISO 8601 time at which the Single Send was last updated", - "format": "date-time" - }, - "created_at": { - "type": "string", - "description": "the ISO 8601 time at which the Single Send was created", - "format": "date-time" - } - }, - "required": [ - "id", - "name", - "abtest", - "status", - "categories", - "is_abtest", - "updated_at", - "created_at" - ], - "x-stoplight": { - "id": "singlesend_response_short", - "name": "singlesend_response_short", - "public": true - } - }, - "cc_bcc_email_object": { - "title": "CC BCC Email Object", - "type": "object", - "properties": { - "email": { - "type": "string", - "format": "email", - "description": "The intended recipient's email address." - }, - "name": { - "type": "string", - "description": "The intended recipient's name." - } - }, - "required": ["email"], - "example": { - "email": "jane_doe@example.com", - "name": "Jane Doe" - }, - "x-stoplight": { - "id": "cc_bcc_email_object", - "name": "CC BCC Email Object", - "public": true - } - }, - "verified-sender-request-schema": { - "title": "Verified Sender Request Schema", - "type": "object", - "properties": { - "nickname": { - "type": "string", - "maxLength": 100 - }, - "from_email": { - "type": "string", - "maxLength": 256, - "format": "email" - }, - "from_name": { - "type": "string", - "maxLength": 256 - }, - "reply_to": { - "type": "string", - "maxLength": 256, - "format": "email" - }, - "reply_to_name": { - "type": "string", - "maxLength": 256 - }, - "address": { - "type": "string", - "maxLength": 100 - }, - "address2": { - "type": "string", - "maxLength": 100 - }, - "state": { - "type": "string", - "maxLength": 2 - }, - "city": { - "type": "string", - "maxLength": 150 - }, - "zip": { - "type": "string", - "maxLength": 10 - }, - "country": { - "type": "string", - "maxLength": 100 - } - }, - "required": ["nickname", "from_email", "reply_to"], - "example": { - "nickname": "Orders", - "from_email": "orders@example.com", - "from_name": "Example Orders", - "reply_to": "orders@example.com", - "reply_to_name": "Example Orders", - "address": "1234 Fake St", - "address2": "PO Box 1234", - "state": "CA", - "city": "San Francisco", - "country": "USA", - "zip": "94105" - }, - "x-stoplight": { - "id": "verified-sender-request-schema", - "name": "Verified Sender Request Schema", - "public": true - } - }, - "verified-sender-response-schema": { - "title": "Verified Sender Response Schema", - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "nickname": { - "type": "string" - }, - "from_email": { - "type": "string" - }, - "from_name": { - "type": "string" - }, - "reply_to": { - "type": "string" - }, - "reply_to_name": { - "type": "string" - }, - "address": { - "type": "string" - }, - "address2": { - "type": "string" - }, - "state": { - "type": "string" - }, - "city": { - "type": "string" - }, - "zip": { - "type": "string" - }, - "country": { - "type": "string" - }, - "verified": { - "type": "boolean" - }, - "locked": { - "type": "boolean" - } - }, - "example": { - "id": 1234, - "nickname": "Example Orders", - "from_email": "orders@example.com", - "from_name": "Example Orders", - "reply_to": "orders@example.com", - "reply_to_name": "Example Orders", - "address": "1234 Fake St.", - "address2": "PO Box 1234", - "state": "CA", - "city": "San Francisco", - "country": "USA", - "zip": "94105", - "verified": true, - "locked": false - }, - "x-stoplight": { - "id": "verified-sender-response-schema", - "name": "Verified Sender Response Schema", - "public": true - } - }, - "ip-access-response": { - "title": "IP Access Response", - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "An array listing all of your allowed IPs.", - "items": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the allowed IP." - }, - "ip": { - "type": "string", - "description": "The allowed IP." - }, - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IP was added to the allow list." - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IPs allow status was most recently updated." - } - } - } - } - }, - "example": { - "result": [ - { - "id": 1, - "ip": "192.168.1.1/32", - "created_at": 1441824715, - "updated_at": 1441824715 - }, - { - "id": 2, - "ip": "192.0.0.0/8", - "created_at": 1441824715, - "updated_at": 1441824715 - }, - { - "id": 3, - "ip": "192.168.1.3/32", - "created_at": 1441824715, - "updated_at": 1441824715 - } - ] - }, - "x-stoplight": { - "id": "ip-access-response", - "name": "IP Access Response", - "public": true - } - }, - "stats-advanced-global-stats": { - "title": "Stats: Advanced Global Stats", - "allOf": [ - { - "$ref": "#/components/schemas/advanced_stats_clicks_opens" - }, - { - "type": "object", - "properties": { - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounce_drops": { - "type": "integer", - "description": "The number of emails that were dropped because of a bounce." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "deferred": { - "type": "integer", - "description": "The number of emails that temporarily could not be delivered. " - }, - "delivered": { - "type": "integer", - "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." - }, - "invalid_emails": { - "type": "integer", - "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." - }, - "processed": { - "type": "integer", - "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." - }, - "requests": { - "type": "integer", - "description": "The number of emails that were requested to be delivered." - }, - "spam_report_drops": { - "type": "integer", - "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." - }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." - }, - "unsubscribe_drops": { - "type": "integer", - "description": "The number of emails dropped due to a recipient unsubscribing from your emails." - }, - "unsubscribes": { - "type": "integer", - "description": "The number of recipients who unsubscribed from your emails." - } - } - } - ], - "x-stoplight": { - "id": "stats-advanced-global-stats", - "name": "Stats: Advanced Global Stats", - "public": true - } - }, - "stats-advanced-stats-base-schema": { - "title": "Stats: Advanced Stats Base Schema", - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date the stats were gathered." - }, - "stats": { - "type": "array", - "description": "The individual email activity stats.", - "items": { - "type": "object", - "properties": { - "metrics": { - "type": "object" - } - } - } - } - } - }, - "x-stoplight": { - "id": "stats-advanced-stats-base-schema", - "name": "Stats: Advanced Stats Base Schema", - "public": true - } - }, - "full-segment": { - "title": "full_segment", - "allOf": [ - { - "$ref": "#/components/schemas/segment_summary" - }, - { - "type": "object", - "properties": { - "contacts_sample": { - "type": "array", - "items": { - "$ref": "#/components/schemas/contact_response" - } - }, - "query_json": { - "type": "object", - "description": "AST representation of the query DSL" - } - }, - "required": ["contacts_sample"] - }, - { - "$ref": "#/components/schemas/segment_write_v2" - } - ], - "example": { - "id": "58567a46-305e-48d1-b4f8-a006c906920e", - "contacts_count": 9266921, - "created_at": "2085-08-08T21:07:05.692Z", - "sample_updated_at": "3407-09-25T04:25:02.140Z", - "updated_at": "4431-05-07T22:23:22.352Z", - "contacts_sample": [ - { - "contact_id": "c1183ada-b784-49ac-9b1f-50e73578a6dc", - "primary_email": "ft88@d.izxx", - "alternate_emails": [ - "yKDUP11FDch@QoU.vwy", - "ZNSN5@czAMqPi.at", - "7wr51kFVVKlcBSH@DWxOueOZepetzBrku.qosk", - "iib-ObtO7Fxz5@vLJPRIFKPOqJGCEqcIDab.ypn" - ], - "first_name": "est", - "last_name": "eiusmod in laboris velit cupidatat", - "address_line_1": "sunt aliqua", - "address_line_2": "sit proident Lorem veniam labore", - "city": "œȎţȸÛ\tč\u000bCŁ", - "state_province_region": "ut proident", - "postal_code": 30296612, - "country": "do reprehenderit qui", - "custom_fields": { - "custom_field_name2": "in consectetur ut aliqua sint", - "custom_field_name1": "esse" - } - } - ], - "name": "culpa", - "query_dsl": "cillum eiusmod", - "parent_list_id": "2357714d-3d82-4c80-826c-b44a4147f81c", - "next_sample_update": "" - }, - "x-stoplight": { - "id": "full-segment", - "name": "full_segment", - "public": true - } - }, - "senders-id-request-body": { - "title": "Senders ID Request Body", - "type": "object", - "properties": { - "nickname": { - "type": "string", - "description": "A nickname for the sender identity. Not used for sending." - }, - "from": { - "type": "object", - "required": ["email", "name"], - "properties": { - "email": { - "type": "string", - "description": "This is where the email will appear to originate from for your recipient" - }, - "name": { - "type": "string", - "description": "This is the name appended to the from email field. IE - Your name or company name." - } - } - }, - "reply_to": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "This is the email that your recipient will reply to." - }, - "name": { - "type": "string", - "description": "This is the name appended to the reply to email field. IE - Your name or company name." - } - }, - "required": ["email"] - }, - "address": { - "type": "string", - "description": "The physical address of the sender identity." - }, - "address_2": { - "type": "string", - "description": "Additional sender identity address information." - }, - "city": { - "type": "string", - "description": "The city of the sender identity." - }, - "state": { - "type": "string", - "description": "The state of the sender identity." - }, - "zip": { - "type": "string", - "description": "The zipcode of the sender identity." - }, - "country": { - "type": "string", - "description": "The country of the sender identity." - } - }, - "required": ["nickname", "from", "address", "city", "country"], - "x-stoplight": { - "id": "senders-id-request-body", - "name": "Senders ID Request Body", - "public": true - } - }, - "enforced-tls-request-response": { - "title": "Enforced TLS Request Response", - "type": "object", - "properties": { - "require_tls": { - "type": "boolean", - "description": "Indicates if you want to require your recipients to support TLS. " - }, - "require_valid_cert": { - "type": "boolean", - "description": "Indicates if you want to require your recipients to have a valid certificate." - } - }, - "example": { - "require_tls": true, - "require_valid_cert": true - }, - "x-stoplight": { - "id": "enforced-tls-request-response", - "name": "Enforced TLS Request Response", - "public": true - } - }, - "singlesend_response": { - "title": "singlesend_response", - "allOf": [ - { - "$ref": "#/components/schemas/singlesend_request" - }, - { - "type": "object", - "properties": { - "id": { - "type": "string", - "format": "uuid" - }, - "status": { - "type": "string", - "enum": ["draft", "scheduled", "triggered"], - "description": "current status of the Single Send" - }, - "updated_at": { - "type": "string", - "description": "the ISO 8601 time at which the Single Send was last updated", - "format": "date-time" - }, - "created_at": { - "type": "string", - "description": "the ISO 8601 time at which the Single Send was created", - "format": "date-time" - }, - "warnings": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - }, - "warning_id": { - "type": "string" - } - } - } - } - }, - "required": ["id", "status", "created_at"] - } - ], - "example": { - "name": "Example API Created Single Send", - "id": "27c21bbf-a12c-440b-b8bf-c526975328ca", - "status": "scheduled", - "created_at": "2020-05-18T17:28:27.272Z", - "send_at": "2020-06-16T00:19:55.106Z", - "categories": ["unique opens"], - "email_config": { - "subject": "", - "html_content": "", - "plain_content": "", - "generate_plain_content": true, - "editor": "code", - "suppression_group_id": null, - "custom_unsubscribe_url": null, - "sender_id": null, - "ip_pool": null - }, - "send_to": { - "list_ids": ["f2fe66a1-43f3-4e3a-87b1-c6a600d805f0"] - } - }, - "x-stoplight": { - "id": "singlesend_response", - "name": "singlesend_response", - "public": true - } - }, - "design-common-fields": { - "title": "Design Common Fields", - "allOf": [ - { - "$ref": "#/components/schemas/design-duplicate-input" - }, - { - "type": "object", - "properties": { - "generate_plain_content": { - "type": "boolean", - "description": "If true, plain_content is always generated from html_content. If false, plain_content is not altered.", - "default": true - }, - "subject": { - "type": "string", - "description": "Subject of the Design.", - "maxLength": 5000 - }, - "categories": { - "type": "array", - "description": "The list of categories applied to the design", - "uniqueItems": true, - "maxItems": 10, - "items": { - "type": "string", - "maxLength": 255 - } - } - } - } - ], - "x-stoplight": { - "id": "design-common-fields", - "name": "Design Common Fields", - "public": true - } - }, - "invalid-email": { - "title": "Invalid Email", - "type": "object", - "properties": { - "created": { - "type": "integer", - "description": "A Unix timestamp indicating when the email address was added to the invalid emails list." - }, - "email": { - "type": "string", - "description": "The email address that was marked as invalid.", - "format": "email" - }, - "reason": { - "type": "string", - "description": "The reason that the email address was marked as invalid." - } - }, - "example": { - "created": 1620141015, - "email": "invalid@example.com", - "reason": "Mail domain mentioned in email address is unknown" - }, - "x-stoplight": { - "id": "invalid-email", - "name": "Invalid Email", - "public": true - } - }, - "email-activity-response-common-fields": { - "title": "Email Activity Response Common Fields", - "type": "object", - "properties": { - "from_email": { - "type": "string", - "format": "email", - "default": "test0@example.com", - "description": "The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account." - }, - "msg_id": { - "type": "string", - "description": "A unique ID assigned to the message. This ID can be used to retrieve activity data for the specific message." - }, - "subject": { - "type": "string", - "description": "The email's subject line." - }, - "to_email": { - "type": "string", - "format": "email", - "description": "The intended recipient's email address." - }, - "status": { - "type": "string", - "description": "The message's status.", - "enum": ["processed", "delivered", "not_delivered"] - } - }, - "x-stoplight": { - "id": "email-activity-response-common-fields", - "name": "Email Activity Response Common Fields", - "public": true - } - }, - "suppressions-request": { - "title": "Suppressions Request Body", - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "description": "The array of email addresses to add or find.", - "items": { - "type": "string", - "format": "email" - } - } - }, - "required": ["recipient_emails"], - "example": { - "recipient_emails": ["test1@example.com", "test2@example.com"] - }, - "x-stoplight": { - "id": "suppressions-request", - "name": "Suppressions Request Body", - "public": true - } - }, - "suppression-group-request-base": { - "title": "Suppression Group Request Base", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of your suppression group. Required when creating a group.", - "maxLength": 30 - }, - "description": { - "type": "string", - "description": "A brief description of your suppression group. Required when creating a group.", - "maxLength": 100 - }, - "is_default": { - "type": "boolean", - "description": "Indicates if you would like this to be your default suppression group." - } - }, - "x-stoplight": { - "id": "suppression-group-request-base", - "name": "Suppression Group Request Base", - "public": true - } - }, - "sso-certificate-body": { - "title": "Single Sign-On Certificate Body", - "type": "object", - "properties": { - "public_certificate": { - "type": "string", - "description": "This certificate is used by Twilio SendGrid to verify that SAML requests are coming from Okta. This is called the X509 certificate in the Twilio SendGrid UI." - }, - "id": { - "type": "number", - "description": "A unique ID assigned to the certificate by SendGrid." - }, - "not_before": { - "type": "number", - "description": "A unix timestamp (e.g., 1603915954) that indicates the time before which the certificate is not valid." - }, - "not_after": { - "type": "number", - "description": "A unix timestamp (e.g., 1603915954) that indicates the time after which the certificate is no longer valid." - }, - "intergration_id": { - "type": "string", - "description": "An ID that matches a certificate to a specific IdP integration." - } - }, - "example": { - "public_certificate": "", - "id": 66138975, - "not_before": 1621289880, - "not_after": 1621289880, - "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" - }, - "x-stoplight": { - "id": "sso-certificate-body", - "name": "Single Sign-On Certificate Body", - "public": true - } - }, - "sso-integration": { - "title": "Single Sign-On Integration", - "allOf": [ - { - "$ref": "#/components/schemas/create-integration-request" - }, - { - "type": "object", - "properties": { - "last_updated": { - "type": "number", - "description": "A timestamp representing the last time the configuration was modified." - }, - "id": { - "type": "string", - "description": "A unique ID assigned to the configuration by SendGrid." - }, - "single_signon_url": { - "type": "string", - "description": "The URL where your IdP should POST its SAML response. This is the Twilio SendGrid URL that is responsible for receiving and parsing a SAML assertion. This is the same URL as the Audience URL when using SendGrid." - }, - "audience_url": { - "type": "string", - "description": "The URL where your IdP should POST its SAML response. This is the Twilio SendGrid URL that is responsible for receiving and parsing a SAML assertion. This is the same URL as the Single Sign-On URL when using SendGrid." - } - }, - "required": ["last_updated"] - } - ], - "x-stoplight": { - "id": "sso-integration", - "name": "Single Sign-On Integration", - "public": true - } - }, - "create-integration-request": { - "title": "Create Integration Request", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of your integration. This name can be anything that makes sense for your organization (eg. Twilio SendGrid)" - }, - "enabled": { - "type": "boolean", - "description": "Indicates if the integration is enabled." - }, - "signin_url": { - "type": "string", - "description": "The IdP's SAML POST endpoint. This endpoint should receive requests and initiate an SSO login flow. This is called the \"Embed Link\" in the Twilio SendGrid UI." - }, - "signout_url": { - "type": "string", - "description": "This URL is relevant only for an IdP-initiated authentication flow. If a user authenticates from their IdP, this URL will return them to their IdP when logging out." - }, - "entity_id": { - "type": "string", - "description": "An identifier provided by your IdP to identify Twilio SendGrid in the SAML interaction. This is called the \"SAML Issuer ID\" in the Twilio SendGrid UI." - }, - "completed_integration": { - "type": "boolean", - "description": "Indicates if the integration is complete." - } - }, - "required": ["name", "enabled", "signin_url", "signout_url", "entity_id"], - "x-stoplight": { - "id": "create-integration-request", - "name": "Create Integration Request", - "public": true - } - }, - "sso-teammate-response": { - "title": "Single Sign-On Teammate Response", - "allOf": [ - { - "$ref": "#/components/schemas/sso-teammate-common-fields" - }, - { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "This should be set to the Teammate's email address." - }, - "is_sso": { - "type": "boolean", - "description": "Indicates if the Teammate authenticates with SendGrid using SSO or with a username and password." - } - } - } - ], - "x-stoplight": { - "id": "sso-teammate-response", - "name": "Single Sign-On Teammate Response", - "public": true - } - }, - "sso-teammate-request": { - "title": "Single Sign-On Teammate Request", - "allOf": [ - { - "$ref": "#/components/schemas/sso-teammate-common-fields" - }, - { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "The permission scopes assigned to the Teammate.", - "items": { - "type": "string" - } - } - }, - "required": ["scopes"] - } - ], - "x-stoplight": { - "id": "sso-teammate-request", - "name": "Single Sign-On Teammate Request", - "public": true - } - }, - "sso-teammates-patch-response": { - "title": "Single Sign-On Teammates PATCH Response", - "allOf": [ - { - "$ref": "#/components/schemas/sso-teammate-response" - }, - { - "type": "object", - "properties": { - "address": { - "type": "string", - "description": "The Teammate’s street address." - }, - "address2": { - "type": "string", - "description": "The Teammate’s apartment number, suite number, or other secondary address information that is not part of the physical street address." - }, - "city": { - "type": "string", - "description": "The Teammate's city." - }, - "company": { - "type": "string", - "description": "The Teammate’s company name." - }, - "country": { - "type": "string", - "description": "The Teammate’s country of residence." - }, - "email": { - "type": "string", - "format": "email" - }, - "phone": { - "type": "string", - "description": "The Teammate’s stored phone number." - }, - "scopes": { - "type": "array", - "description": "The permission scopes assigned to the Teammate.", - "items": { - "type": "string" - } - }, - "state": { - "type": "string", - "description": "The Teammate’s state or province." - }, - "user_type": { - "type": "string", - "description": "A Teammate can be an “admin,” “owner,” or “teammate.” Each role is associated with the scope of the Teammate’s permissions.", - "enum": ["admin", "owner", "teammate"] - }, - "website": { - "type": "string", - "description": "A website associated with the Teammate" - }, - "zip": { - "type": "string", - "description": "The Teammate’s zip code." - } - } - } - ], - "x-stoplight": { - "id": "sso-teammates-patch-response", - "name": "Single Sign-On Teammates PATCH Response", - "public": true - } - }, - "sso-error-response": { - "title": "SSO Error Response", - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "nullable": true, - "type": "string" - }, - "error_id": { - "type": "string" - } - } - }, - "x-stoplight": { - "id": "sso-error-response", - "name": "SSO Error Response", - "public": true - } - }, - "click-tracking": { - "title": "Settings: Click Tracking", - "type": "object", - "properties": { - "enable_text": { - "type": "boolean", - "description": "Indicates if click tracking is enabled for plain text emails." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if click tracking is enabled or disabled." - } - }, - "required": ["enable_text", "enabled"], - "example": { - "enable_text": false, - "enabled": false - }, - "x-stoplight": { - "id": "click-tracking", - "name": "Settings: Click Tracking", - "public": true - } - }, - "sso-teammate-common-fields": { - "title": "Single Sing-On Teammate Common Fields", - "type": "object", - "properties": { - "first_name": { - "type": "string", - "description": "The Teammate’s first name." - }, - "last_name": { - "type": "string", - "description": "The Teammate’s last name." - }, - "email": { - "type": "string", - "format": "email", - "description": "The Teammate’s email address. This email address will also function as the Teammate’s username and must match the address assigned to the user in your IdP. This address cannot be changed after the Teammate is created." - }, - "is_admin": { - "type": "boolean", - "description": "Indicates if the Teammate has admin permissions." - }, - "is_read_only": { - "type": "boolean", - "description": "Indicates if the Teammate has read_only permissions." - } - }, - "required": ["first_name", "last_name", "email"], - "x-stoplight": { - "id": "sso-teammate-common-fields", - "name": "Single Sing-On Teammate Common Fields", - "public": true - } - }, - "spam-reports-response": { - "title": "Spam Reports Response", - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer", - "description": "A Unix timestamp that indicates when the recipient marked your message as spam." - }, - "email": { - "type": "string", - "description": "The email address of the recipient that marked your message as spam.", - "format": "email" - }, - "ip": { - "type": "string", - "description": "The IP address that the message was sent from." - } - }, - "required": ["created", "email", "ip"] - }, - "example": [ - { - "created": 1443651141, - "email": "user1@example.com", - "ip": "10.63.202.100" - }, - { - "created": 1443651154, - "email": "user2@example.com", - "ip": "10.63.202.100" - } - ], - "x-stoplight": { - "id": "spam-reports-response", - "name": "Spam Reports Response", - "public": true - } - }, - "blocks-response": { - "title": "Blocks Response", - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer", - "description": "A Unix timestamp indicating when the email address was added to the blocks list." - }, - "email": { - "type": "string", - "description": "The email address that was added to the block list.", - "format": "email" - }, - "reason": { - "type": "string", - "description": "An explanation for the reason of the block." - }, - "status": { - "type": "string", - "description": "The status of the block." - } - }, - "required": ["created", "email", "reason", "status"] - }, - "example": [ - { - "created": 1443651154, - "email": "example@example.com", - "reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host", - "status": "4.0.0" - } - ], - "x-stoplight": { - "id": "blocks-response", - "name": "Blocks Response", - "public": true - } - }, - "ip_pool_response": { - "title": "IP Pools: Pool Resp", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the IP pool." - } - }, - "example": { - "name": "sunt sint enim" - }, - "x-stoplight": { - "id": "ip_pool_response", - "name": "IP Pools: Pool Resp", - "public": true - } - }, - "sender-id-request": { - "title": "Sender ID Request", - "type": "object", - "properties": { - "nickname": { - "type": "string", - "description": "A nickname for the sender identity. Not used for sending." - }, - "from": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address from which your recipient will receive emails." - }, - "name": { - "type": "string", - "description": "The name appended to the from email field. Typically your name or company name." - } - } - }, - "reply_to": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address to which your recipient will reply." - }, - "name": { - "type": "string", - "description": "The name appended to the reply to email field. Typically your name or company name." - } - } - }, - "address": { - "type": "string", - "description": "The physical address of the sender identity." - }, - "address_2": { - "type": "string", - "description": "Additional sender identity address information." - }, - "city": { - "type": "string", - "description": "The city of the sender identity." - }, - "state": { - "type": "string", - "description": "The state of the sender identity." - }, - "zip": { - "type": "string", - "description": "The zipcode of the sender identity." - }, - "country": { - "type": "string", - "description": "The country of the sender identity." - } - }, - "example": { - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States" - }, - "x-stoplight": { - "id": "sender-id-request", - "name": "Sender ID Request", - "public": true - } - }, - "segment_status_response": { - "title": "segment_status_response", - "type": "object", - "description": "Segment status indicates whether the segment's contacts will be updated periodically", - "properties": { - "query_validation": { - "type": "string", - "description": "Status of query validation. PENDING, VALID, or INVALID" - }, - "error_message": { - "type": "string", - "description": "Describes any errors that were encountered during query validation" - } - }, - "required": ["query_validation"], - "x-stoplight": { - "id": "segment_status_response", - "name": "segment_status_response", - "public": true - } - }, - "all_segments_response": { - "title": "all_segments_response", - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 36, - "maxLength": 36, - "format": "uuid", - "description": "ID assigned to the segment when created." - }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100, - "description": "Name of the segment." - }, - "contacts_count": { - "type": "integer", - "description": "Total number of contacts present in the segment" - }, - "created_at": { - "type": "string", - "description": "ISO8601 timestamp of when the object was created" - }, - "updated_at": { - "type": "string", - "description": "ISO8601 timestamp of when the object was last updated" - }, - "sample_updated_at": { - "type": "string", - "description": "ISO8601 timestamp of when the samples were last updated" - }, - "next_sample_update": { - "type": "string", - "description": "ISO8601 timestamp of when the samples will be next updated" - }, - "parent_list_ids": { - "type": "array", - "description": "The array of list ids to filter contacts on when building this segment. It allows only one such list id for now. We will support more in future", - "uniqueItems": true, - "items": { - "type": "string" - } - }, - "query_version": { - "type": "string", - "description": "If not set, segment contains a query for use with Segment v1 APIs. If set to '2', segment contains a SQL query for use in v2." - }, - "_metadata": { - "$ref": "#/components/schemas/_metadata" - }, - "status": { - "$ref": "#/components/schemas/segment_status_response" - } - }, - "required": [ - "id", - "name", - "contacts_count", - "created_at", - "updated_at", - "sample_updated_at", - "next_sample_update", - "parent_list_ids", - "query_version", - "status" - ], - "x-stoplight": { - "id": "all_segments_response", - "name": "all_segments_response", - "public": true - } - }, - "segment_summary_v2": { - "title": "segment_summary", - "type": "object", - "description": "", - "properties": { - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/segment_summary" - } - } - }, - "x-stoplight": { - "id": "segment_summary_v2", - "name": "segment_summary", - "public": true - } - }, - "segment_response": { - "title": "segment_response", - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 36, - "maxLength": 36, - "format": "uuid", - "description": "ID assigned to the segment when created." - }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100, - "description": "Name of the segment." - }, - "query_dsl": { - "type": "string", - "description": "SQL query which will filter contacts based on the conditions provided" - }, - "contacts_count": { - "type": "integer", - "description": "Total number of contacts present in the segment" - }, - "contacts_sample": { - "type": "array", - "description": "A subset of all contacts that are in this segment", - "items": { - "$ref": "#/components/schemas/contact_response" - } - }, - "created_at": { - "type": "string", - "description": "ISO8601 timestamp of when the object was created" - }, - "updated_at": { - "type": "string", - "description": "ISO8601 timestamp of when the object was last updated" - }, - "sample_updated_at": { - "type": "string", - "description": "ISO8601 timestamp of when the samples were last updated" - }, - "next_sample_update": { - "type": "string", - "description": "ISO8601 timestamp of when the samples will be next updated" - }, - "parent_list_ids": { - "type": "array", - "description": "The array of list ids to filter contacts on when building this segment. It allows only one such list id for now. We will support more in future", - "uniqueItems": true, - "items": { - "type": "string" - } - }, - "query_version": { - "type": "string", - "description": "If not set, segment contains a Query for use with Segment v1 APIs. If set to '2', segment contains a SQL query for use in v2." - }, - "status": { - "$ref": "#/components/schemas/segment_status_response" - } - }, - "required": [ - "id", - "name", - "query_dsl", - "contacts_count", - "contacts_sample", - "created_at", - "updated_at", - "sample_updated_at", - "next_sample_update", - "parent_list_ids", - "query_version", - "status" - ], - "x-stoplight": { - "id": "segment_response", - "name": "segment_response", - "public": true - } - }, - "errors-seg-v2": { - "title": "errors-seg", - "type": "object", - "description": "If the request is incorrect, an array of errors will be returned.", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string", - "description": "the field in the request body that is incorrect" - }, - "message": { - "type": "string", - "description": "a description of what is specifically wrong with the field passed in the request" - } - }, - "required": ["field", "message"] - } - } - }, - "required": ["errors"], - "x-stoplight": { - "id": "errors-seg-v2", - "name": "errors-seg", - "public": true - } - }, - "segment_write_v2": { - "title": "segment_write", - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100, - "description": "Name of the segment." - }, - "parent_list_ids": { - "type": "array", - "description": "The array of list ids to filter contacts on when building this segment. It allows only one such list id for now. We will support more in future", - "uniqueItems": true, - "items": { - "type": "string" - } - }, - "query_dsl": { - "type": "string", - "description": "SQL query which will filter contacts based on the conditions provided" - } - }, - "required": ["name", "query_dsl"], - "x-stoplight": { - "id": "segment_write_v2", - "name": "segment_write", - "public": true - } - }, - "segment_update": { - "title": "segment_update", - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100, - "description": "Name of the segment." - }, - "query_dsl": { - "type": "string", - "description": "SQL query which will filter contacts based on the conditions provided" - } - }, - "x-stoplight": { - "id": "segment_update", - "name": "segment_update", - "public": true - } - }, - "abbv-message": { - "title": "Abbv. Message", - "type": "object", - "properties": { - "from_email": { - "type": "string" - }, - "msg_id": { - "type": "string" - }, - "subject": { - "type": "string" - }, - "to_email": { - "type": "string" - }, - "status": { - "type": "string", - "enum": ["processed", "delivered", "not_delivered"] - }, - "opens_count": { - "type": "integer" - }, - "clicks_count": { - "type": "integer" - }, - "last_event_time": { - "type": "string", - "description": "iso 8601 format" - } - }, - "required": [ - "from_email", - "msg_id", - "subject", - "to_email", - "status", - "opens_count", - "clicks_count", - "last_event_time" - ], - "example": { - "from_email": "from@test.com", - "msg_id": "abc123", - "subject": "anim Duis sint veniam", - "to_email": "test@test.com", - "status": "processed", - "opens_count": 1, - "clicks_count": 2, - "last_event_time": "2017-10-13T18:56:21Z" - } - }, - "message": { - "title": "Message", - "type": "object", - "properties": { - "from_email": { - "type": "string", - "pattern": "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b" - }, - "msg_id": { - "type": "string", - "minLength": 5, - "maxLength": 50, - "pattern": "^[A-Za-z0-9]+" - }, - "subject": { - "type": "string", - "minLength": 3, - "maxLength": 255 - }, - "to_email": { - "type": "string", - "pattern": "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b" - }, - "status": { - "type": "string", - "description": "Quick summary of the status of a message", - "enum": ["processed", "not_delivered", "delivered"] - }, - "template_id": { - "type": "string", - "format": "uuid" - }, - "asm_group_id": { - "type": "integer", - "minimum": 1 - }, - "teammate": { - "type": "string", - "description": "Teammate's username", - "minLength": 0, - "maxLength": 64, - "pattern": "^$|^[A-Za-z0-9]+" - }, - "api_key_id": { - "type": "string", - "minLength": 3, - "maxLength": 50, - "pattern": "^[A-Za-z0-9]+" - }, - "events": { - "type": "array", - "description": "List of events related to email message", - "items": { - "title": "Event", - "type": "object", - "properties": { - "event_name": { - "type": "string", - "description": "Name of event", - "enum": [ - "bounced", - "opened", - "clicked", - "processed", - "dropped", - "delivered", - "deferred", - "spam_report", - "unsubscribe", - "group_unsubscribe", - "group_resubscribe" - ] - }, - "processed": { - "description": "Date of when event occurred", - "type": "string" - }, - "reason": { - "type": "string", - "description": "Explanation of what caused \"bounced\", \"deferred\", or \"blocked\". Usually contains error message from the server - e.g. message from gmail why mail was deferred", - "maxLength": 1024 - }, - "attempt_num": { - "type": "integer", - "description": "Used with \"deferred\" events to indicate the attempt number out of 10. One \"deferred\" entry will exists under events array for each time a message was deferred with error message from the server. ", - "minimum": 1, - "maximum": 10 - }, - "url": { - "type": "string", - "description": "Used with \"clicked\" event to indicate which url the user clicked.", - "pattern": "^((http[s]?|ftp):\\/)?\\/?([^:\\/\\s]+)((\\/\\w+)*\\/)([\\w\\-\\.]+[^#?\\s]+)(.*)?(#[\\w\\-]+)?$" - }, - "bounce_type": { - "type": "string", - "description": "Use to distinguish between types of bounces", - "enum": ["bounced", "blocked", "expired"] - }, - "http_user_agent": { - "type": "string", - "description": "Client recipient used to click or open message" - }, - "mx_server": { - "type": "string", - "description": "For example mx.gmail.com" - } - }, - "required": [ - "event_name", - "processed", - "url", - "bounce_type", - "http_user_agent", - "mx_server" - ], - "example": { - "event_name": "bounced", - "processed": "2017-10-13T18:56:21Z", - "reason": "some reason", - "url": "http://3LX,MU}N=B8'd,K}>bEma{l~!ad%peIF}y>qHfLPWQ$l9b\\!6.1H?$Z9H\"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0\"Q/-4dV\"Yk3QGg[(O86=Pf\"e17K4'r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*ObEma{l~!ad%peIF}y>qHfLPWQ$l9b\\!6.1H?$Z9H\"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0\"Q/-4dV\"Yk3QGg[(O86=Pf\"e17K4'r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*ObEma{l~!ad%peIF}y>qHfLPWQ$l9b\\!6.1H?$Z9H\"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0\"Q/-4dV\"Yk3QGg[(O86=Pf\"e17K4'r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*O