{ "openapi": "3.0.0", "info": { "title": "Optimized App API", "description": "API for managing profiles, batches, and campaign scheduling in Optimized.App.\n\n# Introduction\n\nTo begin utilizing Optimized.App, it's essential to:\n\n1. Obtain an API Token\nAccess to the API is granted only through a valid API Token. Note: API Tokens can only be created by an organization administrator. You can generate your token via the Organization Settings section, under Integration -> Api Tokens on the Optimized.App dashboard.\n\n2. Understand Rate and Usage Limits\nOptimized.App has specific rate and usage limitations. Familiarize yourself with these to ensure uninterrupted service.\n\n3. Secure Communication Protocol\nOptimized.App mandates the use of HTTPS-secured communications.\nAny requests sent via HTTP return an HTTP 301 redirect to the corresponding HTTPS resources.\n\n4. Response Format\nAll responses from Optimized.App are provided in JSON format, ensuring a standardized and easy-to-parse structure for your applications.\n\n5. All datetime values in requests and responses are in UTC timezone. Responses are formatted according to ISO 8601 standard (YYYY-MM-DDThh:mm:ss.sssZ).\n\nBy following these guidelines, you'll be set to effectively integrate and work with Optimized.App's API.\n\n# Authentication\n\nTo begin utilizing Optimized.App, it's essential to:\n\n1. Obtain an API Token\nAccess to the API is granted only through a valid API Token. Note: API Tokens can only be created by an organization administrator. You can generate your token via the Organization Settings section, under Integration -> Api Tokens on the Optimized.App dashboard.\n\nYou must include an API token in each request to the Optimized.App API with the Authorization request header.\n\nExample: `Authorization: Bearer [API-TOKEN]`\n\nIf an API token is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code.\n\n# Rate and Usage Limits\n\nThe basic rate limit is 250 requests per minute per user basis. Also, depending on your plan, you may have different usage limits. If you exceed either limit, your request will return an HTTP 429 Too Many Requests status code.\n\nThe following set of headers are returned on the response to help you identify your use status:\n\n| Header | Description |\n| ------ | ----------- |\n| X-Ratelimit-Limit | The maximum number of requests that the consumer is permitted to make per minute. |\n| X-Ratelimit-Remaining | The number of requests remaining in the current rate limit window. |\n| X-Ratelimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. This header is only present when maximum number of requests has been consumed for time period. |\n\n## Endpoint Specific Rate Limits\n\n| Endpoint | Description |\n| ------ | ----------- |\n| Profile importing with scheduling | This is a group based rate limit for 10 requests per minute. |\n\n# Errors\n\nOptimized.App employs standard HTTP response codes to signify the outcome of an API request. Typically, codes within the 2xx range signify a successful operation. Codes within the 4xx range point to an error coming from the provided information (for example, missing a necessary parameter or having invalid data). Codes in the 5xx range are indicative of issues with Optimized.App servers, though these occurrences are uncommon.\n\n| HTTP status code | Description |\n| ------ | ----------- |\n| 200 | Request was made successfully. |\n| 201 | Request was made successfully and a resource was created. |\n| 204 | Request was made successfully and no content was returned. |\n| 400 | The request was rejected, often due to missing a required parameter. |\n| 401 | API token is not valid. |\n| 403 | API token has no permission to perform the request. |\n| 404 | The requested resource does not exist. |\n| 405 | The request method is not allowed for the resource. |\n| 422 | The request was rejected, often due to invalid client data. |\n| 429 | Too many requests hit the API too quickly. We advise implementing an exponential backoff strategy for your requests. |\n| 500 | Something went wrong on our end. |\n| 503 | An unexpected spike in API access traffic. The server is usually operational within a short period of time. If the outage persists or you receive any other form of an HTTP 5XX error, please contact support. |\n\n## Validation Errors (422 Unprocessable Entity)\n\nWhen a request fails validation, the API will respond with a `422 Unprocessable Entity` status code and a JSON response containing detailed information about the validation errors.\n\n### Validation Error Format\n\nWhen validation fails for a request, the API will return a JSON response that includes:\n\n1. A high-level error `message` that summarizes the validation issues\n2. An `errors` object containing detailed validation error messages organized by field\n\n```json\n{\n \"message\": \"The fail on missing attributes field must be true or false.\",\n \"errors\": {\n \"fail_on_missing_attributes\": [\n \"The fail on missing attributes field must be true or false.\"\n ]\n }\n}\n```\n\n### Understanding the Validation Error Response\n\n- **message**: A summary of validation errors that occurred. If there are multiple errors, the message will indicate how many additional errors exist beyond the first one mentioned.\n\n- **errors**: An object where:\n - Each key represents a field that failed validation\n - Each value is an array of error messages for that field\n - A field may have multiple error messages if it fails multiple validation rules\n\n### Handling Array Validation Errors\n\nWhen validating array elements, the error keys will include the array indices:\n\n```json\n{\n \"message\": \"The profiles.1.person.email_address must be a valid email address. (and 1 more error)\",\n \"errors\": {\n \"profiles.1.person.email_address\": [\n \"The profiles.1.person.email_address must be a valid email address.\"\n ],\n \"profiles.0.person.phone_number\": [\n \"The profiles.0.person.phone_number field contains an invalid number.\"\n ]\n }\n}\n```\n\nFor nested fields using \"dot\" notation, error keys in the response will maintain this notation for easy identification:\n\n## Best Practices for Handling Validation Errors\n\nWhen developing an integration with the Optimized.App API, consider these best practices for handling validation errors:\n\n1. **Always check for the HTTP status code** first - a status code of 422 indicates validation errors.\n\n2. **Extract field-specific errors** from the `errors` object to display targeted feedback to your users.\n\n3. **Display all validation errors** to users at once rather than one at a time to improve user experience.\n\n4. **For form submissions**, map the error field names in the API response to your form field names for proper error display.\n\n5. **Implement client-side validation** that mirrors the API's validation rules to provide faster feedback to users before submitting requests to the API.\n\nBy properly handling validation errors, you can create a smoother integration experience with the Optimized.App API and provide clear guidance to users when their inputs need correction.\n\n# Pagination\n\nOptimized.App API uses pagination for endpoints that return collections of resources to improve performance and reduce response sizes. Pagination information is included in the JSON response body and follows a consistent format across all paginated endpoints.\n\n## Pagination Response Format\n\nPaginated responses include the following standard fields:\n\n| Field | Description |\n|-------|-------------|\n| `current_page` | The current page number |\n| `data` | Array containing the actual resource items for the current page |\n| `first_page_url` | URL for the first page of results |\n| `from` | Position of the first item on the current page |\n| `next_page_url` | URL for the next page (null if there is no next page) |\n| `path` | Base URL path without query parameters |\n| `per_page` | Number of items displayed per page |\n| `prev_page_url` | URL for the previous page (null if there is no previous page) |\n| `to` | Position of the last item on the current page |\n\n## Example Pagination Response\n\n```json\n{\n \"current_page\": 1,\n \"data\": [\n {\n \"uuid\": \"9e072d6f-11af-4a13-a373-924a516d3795\",\n \"metadata\": [],\n \"name\": \"My Group\",\n \"created_at\": \"2025-01-22T09:04:02.000000Z\",\n \"updated_at\": \"2025-01-22T09:04:02.000000Z\",\n \"deleted_at\": null\n },\n {\n \"uuid\": \"9e072d6f-0ed2-486a-baca-58f889f55cd4\",\n \"metadata\": [],\n \"name\": \"My second group\",\n \"created_at\": \"2025-01-22T09:04:02.000000Z\",\n \"updated_at\": \"2025-01-22T09:04:02.000000Z\",\n \"deleted_at\": null\n }\n ],\n \"first_page_url\": \"https://api.optimized.app/v1/my-groups&page=1\",\n \"from\": 1,\n \"next_page_url\": null,\n \"path\": \"https://api.optimized.app/v1/my-groups\",\n \"per_page\": 25,\n \"prev_page_url\": null,\n \"to\": 2\n}\n```\n\n### Navigating Paginated Pages\n\nBy default, paginated endpoints return 25 items per page.\n\nTo navigate through pages, you can:\n\n1. Use the `page` parameter to request a specific page\n2. Follow the URLs provided in the pagination fields:\n - `first_page_url`: Navigate to the first page\n - `next_page_url`: Navigate to the next page\n - `prev_page_url`: Navigate to the previous page\n\n### Sorting Paginated Results\n\nYou can sort paginated results using the `sort` parameter:\n\n```\nGET /v1/my-groups?sort=created_at\n```\n\nFor descending order, prefix the field name with a minus sign:\n\n```\nGET /v1/my-groups?sort=-created_at\n```\n\n## Best Practices for Pagination\n\n1. **Always check for null values** in `next_page_url` and `prev_page_url` to determine if there are more pages available.\n\n2. **Use the provided URLs** instead of constructing your own to ensure proper formatting and compatibility with API changes.\n\n3. **Implement cache invalidation strategies** when working with paginated data that may change frequently.\n\n4. **Be mindful of rate limits** when making multiple requests to retrieve all pages of a resource. Implement appropriate backoff strategies if necessary.\n", "version": "2.0.1" }, "servers": [ { "url": "https://api.optimized.app", "description": "Production server" } ], "paths": { "/v1/groups/{GROUP_ID}/batches": { "post": { "operationId": "createBatch", "summary": "Create a new batch of profiles with scheduling", "description": "Creates a new batch of profiles with scheduling information.\n\n**This endpoint has a special rate limit of 10 requests per minute per group.**\n\n#### Errors\n\nThis endpoint may fail with a validation error (HTTP 422). See the [Errors](/api/section/errors) section for details on error response format.\n\nCommon validation errors include: Duplicate or non-unique `external_id`, invalid phone number / email address format\n", "parameters": [ { "name": "GROUP_ID", "in": "path", "required": true, "description": "The unique identifier of the group", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_tag": { "description": "Optional. Profile tag information for the batch. If missing, a new one will be created automatically.", "oneOf": [ { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 5, "maxLength": 255, "description": "Name of the profile tag. If an exact match exists, that tag will be used. Otherwise, a new tag will be created." } } }, { "type": "object", "required": [ "uuid" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID of an existing profile tag. Can be provided instead of name." } } } ] }, "profiles": { "type": "array", "description": "Array of profile objects to be created in this batch.\n**Limit:** You can include up to 50 profiles in a single request.\n", "maxItems": 50, "items": { "type": "object", "required": [ "person" ], "properties": { "external_id": { "type": "string", "maxLength": 255, "description": "External identifier for the profile. Must be unique within your organization.", "nullable": true }, "person": { "type": "object", "required": [], "properties": { "first_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "First name of the person." }, "last_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Last name of the person." }, "email_address": { "type": "string", "format": "email", "maxLength": 255, "nullable": true, "description": "Email address of the person." }, "phone_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "Phone number of the person in international format (e.g., +35840123456)." } } }, "attributes": { "type": "array", "maxItems": 50, "description": "Optional. Array of custom attributes for the profile.\n\nBy default, any attribute that does not already exist will be created automatically.\n\nIf `fail_on_missing_attributes` is set to `true`, then all attributes listed here must already exist in the system (created via the UI or API); otherwise, the request will fail with a validation error.\n", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "maxLength": 255, "description": "Name of the attribute. Must only contain English letters, numbers, underscores (_), or hyphens (-). No spaces or other special characters allowed.\n" }, "value": { "type": "string", "maxLength": 255, "description": "Value of the attribute." } } } } } } }, "schedule": { "type": "object", "description": "Optional. Scheduling information for the batch. If omitted, the batch will be imported without scheduling.", "properties": { "start_at": { "type": "string", "format": "date-time", "description": "Optional. When to start the scheduled campaign in UTC. Format 'YYYY-MM-DD HH:MM:SS'. If missing, the campaign will start immediately." }, "calls_per_minute": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 60, "description": "Optional. The maximum number of calls per minute for the scheduled campaign. Must be between 1 and 60. If omitted, the default rate will be used.\n" }, "campaign": { "description": "Campaign information for scheduling. Either `uuid` or `name` must be provided, but not both.", "oneOf": [ { "type": "object", "required": [ "uuid" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID of the campaign to schedule." } } }, { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 5, "maxLength": 255, "description": "Full name of the campaign. Can be provided instead of uuid." } } } ] } } }, "fail_on_missing_attributes": { "type": "boolean", "description": "If true, all attributes must already exist in the system.\nIf any attribute does not exist (i.e., has not been created from the UI or via the API), the request will fail with a validation errors.\n\nIf false or omitted, all missing attributes will be created automatically.\n", "default": false } }, "required": [ "profiles" ] } } } }, "responses": { "200": { "description": "Batch created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "array", "description": "Metadata associated with the batch", "items": { "type": "object" } }, "profiles": { "type": "array", "description": "List of profiles created in this batch", "items": { "type": "object", "properties": { "external_id": { "type": "string", "description": "External identifier for the profile. Unique within your organization.", "nullable": true }, "uuid": { "type": "string", "format": "uuid", "description": "UUID of the created profile" } } } }, "uuid": { "type": "string", "format": "uuid", "description": "UUID of the created batch" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the batch was last updated" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the batch was created" }, "group": { "$ref": "#/components/schemas/Group" }, "campaign": { "$ref": "#/components/schemas/Campaign" }, "profile_tag": { "$ref": "#/components/schemas/ProfileTag" }, "schedule": { "$ref": "#/components/schemas/Schedule" } }, "example": { "metadata": [], "profiles": [ { "external_id": "0000012", "uuid": "9ed84352-3e00-4fa0-9705-27f566205d5f" } ], "uuid": "9ed84352-4652-4892-9fdc-cd0e1738d432", "updated_at": "2025-05-06T07:33:15.000000Z", "created_at": "2025-05-06T07:33:15.000000Z", "group": { "uuid": "9e072d6f-0ed2-486a-baca-58f889f55cd4", "metadata": [], "name": "My group", "created_at": "2025-01-22T09:04:02.000000Z", "updated_at": "2025-01-22T09:04:02.000000Z", "deleted_at": null, "type": { "uuid": "9e072d6e-d6cc-4a15-92ab-3101057353ee", "name": "Organization", "created_at": "2025-01-22T09:04:01.000000Z", "updated_at": "2025-01-22T09:04:01.000000Z", "deleted_at": null } }, "campaign": { "uuid": "9e679c93-ff33-4b1e-bfad-1ac77afe1aef", "status": "untested", "name": "Voice with question", "description": "My complicated voice with question campaign", "metadata": [], "created_at": "2025-03-11T07:34:17.000000Z", "updated_at": "2025-04-08T06:28:10.000000Z", "deleted_at": null, "hidden_at": null, "view": "broadcast", "revision": 2 }, "profile_tag": { "name": "Voice with question - 202505060733 - e39f2636", "type": "basic", "is_anonymized": false, "uuid": "9ed84352-3b85-4018-a097-e4e15ff3b127", "updated_at": "2025-05-06T07:33:15.000000Z", "created_at": "2025-05-06T07:33:15.000000Z" }, "schedule": { "metadata": [], "status": "scheduled", "start_at": "2025-05-06T07:33:15.000000Z", "uuid": "9ed84352-453d-4a9d-82ad-a71062f44596", "updated_at": "2025-05-06T07:33:15.000000Z", "created_at": "2025-05-06T07:33:15.000000Z" } } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Token", "description": "The Optimized.App uses API Tokens for authentication. You can generate an Optimized.App API token from the Optimized.app - Organizational settings.\n\nYou must include an API token in each request to the Optimized.App API with the Authorization request header.\n\nExample: `Authorization: Bearer [API-TOKEN]`\n\nIf an API token is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code.\n" } }, "schemas": { "Campaign": { "type": "object", "description": "Information about a campaign.", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID of the campaign" }, "status": { "type": "string", "description": "Status of the campaign", "enum": [ "tested", "untested" ] }, "name": { "type": "string", "description": "Name of the campaign" }, "description": { "type": "string", "description": "Description of the campaign" }, "metadata": { "type": "array", "description": "Metadata associated with the campaign", "items": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the campaign was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the campaign was last updated" }, "deleted_at": { "type": "string", "format": "date-time", "description": "Timestamp when the campaign was deleted (if applicable)", "nullable": true }, "hidden_at": { "type": "string", "format": "date-time", "description": "Timestamp when the campaign was hidden (if applicable)", "nullable": true }, "view": { "type": "string", "description": "View type of the campaign", "enum": [ "broadcast", "sequence" ] }, "revision": { "type": "integer", "description": "Revision number of the campaign" } } }, "ProfileTag": { "type": "object", "description": "Information about the profile tag for this batch. In the Optimized.App UI, a profile tag is referred to as a \"Contact list\". If this field is not provided, a new Contact list will be created automatically and a name will be generated by the system. Use this object to associate the batch with an existing Contact list or to create a new one with a custom name.\n", "properties": { "name": { "type": "string", "minLength": 5, "maxLength": 255, "description": "Name of the profile tag (Contact list)" }, "type": { "type": "string", "description": "Type of the profile tag", "enum": [ "basic", "hidden" ] }, "is_anonymized": { "type": "boolean", "description": "Indicates whether all profile data in this profile tag (Contact list) is currently anonymized. If true, all profiles associated with this tag have their personally identifiable information anonymized.\n" }, "uuid": { "type": "string", "format": "uuid", "description": "UUID of the profile tag" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the profile tag was last updated" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the profile tag was created" } } }, "Schedule": { "type": "object", "description": "Information about the schedule if included (null if no schedule was set).", "nullable": true, "properties": { "metadata": { "type": "array", "description": "Metadata associated with the schedule", "items": { "type": "object" } }, "status": { "type": "string", "description": "Status of the schedule", "enum": [ "scheduled" ] }, "start_at": { "type": "string", "format": "date-time", "description": "Timestamp when the schedule starts" }, "uuid": { "type": "string", "format": "uuid", "description": "UUID of the schedule" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the schedule was last updated" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the schedule was created" } } }, "Group": { "type": "object", "description": "Information about the group this batch belongs to.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID of the group" }, "metadata": { "type": "array", "description": "Metadata associated with the group", "items": { "type": "object" } }, "name": { "type": "string", "description": "Name of the group" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the group was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the group was last updated" }, "deleted_at": { "type": "string", "format": "date-time", "description": "Timestamp when the group was deleted (if applicable)", "nullable": true }, "type": { "$ref": "#/components/schemas/GroupType" } } }, "GroupType": { "type": "object", "description": "Type information for the group.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID of the group type" }, "name": { "type": "string", "description": "Name of the group type" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the group type was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the group type was last updated" }, "deleted_at": { "type": "string", "format": "date-time", "description": "Timestamp when the group type was deleted (if applicable)", "nullable": true } } } } }, "security": [ { "BearerAuth": [] } ], "x-rateLimit": { "description": "## Rate and Usage Limits\n\nThe basic rate limit is 250 requests per minute per user basis. Also, depending on your plan, you may have different usage limits. If you exceed either limit, your request will return an HTTP 429 Too Many Requests status code.\n\nThe following set of headers are returned on the response to help you identify your use status:\n\n| Header | Description |\n| ------ | ----------- |\n| X-Ratelimit-Limit | The maximum number of requests that the consumer is permitted to make per minute. |\n| X-Ratelimit-Remaining | The number of requests remaining in the current rate limit window. |\n| X-Ratelimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. This header is only present when maximum number of requests has been consumed for time period. |\n\n### Endpoint Specific Rate Limits\n\n| Endpoint | Description |\n| ------ | ----------- |\n| Profile importing | This is a group based rate limit for 10 requests per minute. |\n" }, "x-errorResponses": { "description": "## Errors\n\nOptimized.App employs standard HTTP response codes to signify the outcome of an API request. Typically, codes within the 2xx range signify a successful operation. Codes within the 4xx range point to an error coming from the provided information (for example, missing a necessary parameter or having invalid data). Codes in the 5xx range are indicative of issues with Optimized servers, though these occurrences are uncommon.\n\n| HTTP status code | Description |\n| ------ | ----------- |\n| 2xx | Request was made successfully. |\n| 400 | The request was rejected, often due to missing a required parameter. |\n| 401 | API token is not valid. |\n| 403 | API token has no permission to perform the request. |\n| 404 | The requested resource does not exist. |\n| 429 | Too many requests hit the API too quickly. We advise implementing an exponential backoff strategy for your requests. |\n| 5xx | Something went wrong on our end. |\n| 503 | An unexpected spike in API access traffic. The server is usually operational within a short period of time. If the outage persists or you receive any other form of an HTTP 5XX error, please contact support. |\n" } }