{ "openapi": "3.1.0", "info": { "title": "BounceShift API Documentation", "version": "1.0.0", "description": "# BounceShift Email Validation API\n\nBounceShift provides a powerful email validation API to help you verify email addresses, reduce bounce rates, and protect your sender reputation.\n\n## Authentication\n\nAll API requests require authentication using a Bearer token. Generate API tokens from your [Dashboard](\/dashboard\/api-tokens).\n\n```bash\ncurl -X POST https:\/\/api.bounceshift.com\/v1\/validate\/single \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n -H \"Content-Type: application\/json\" \\\n -H \"X-Organization-ID: YOUR_ORG_ID\" \\\n -d '{\"email\": \"test@example.com\"}'\n```\n\n## Organization Selection\n\nAPI requests operate in the context of an organization. You can specify which organization to use with the `X-Organization-ID` header:\n\n| Header | Description |\n|--------|-------------|\n| `X-Organization-ID` | The ID of the organization to use for this request. If not provided, your default organization is used. |\n\n**Example:**\n```bash\ncurl -X GET https:\/\/api.bounceshift.com\/v1\/credits\/balance \\\n -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n -H \"X-Organization-ID: 123\"\n```\n\nYou can find your Organization ID in your [Dashboard Settings](\/dashboard\/preferences).\n\n## Rate Limits\n\nAPI requests are rate limited to **60 requests per minute** per API token.\n\n## Token Permissions\n\nWhen creating an API token, you can configure the following permissions:\n\n| Permission | Description |\n|------------|-------------|\n| `validate:single` | Validate individual email addresses |\n| `validate:batch` | Create and manage batch validations |\n| `credits:read` | View credit balance |\n\n## Response Codes\n\n| Status | Description |\n|--------|-------------|\n| 200 | Success |\n| 400 | Bad Request - Invalid parameters or no organization selected |\n| 401 | Unauthorized - Invalid or missing token |\n| 402 | Payment Required - Insufficient credits |\n| 403 | Forbidden - Token lacks required permission or invalid organization |\n| 404 | Not Found - Resource not found |\n| 422 | Unprocessable Entity - Validation error |\n| 429 | Too Many Requests - Rate limit exceeded |\n" }, "servers": [ { "url": "https:\/\/api.bounceshift.com\/v1" } ], "security": [ { "http": [] } ], "paths": { "\/validate\/batch": { "post": { "operationId": "create-batch", "description": "Upload a CSV file containing email addresses for batch validation.\nThe CSV must have an 'email' column header. Processing happens asynchronously.\n\n**Required Permission:** `validate:batch`\n\n**Rate Limit:** 60 requests per minute", "summary": "Create Batch Validation", "tags": [ "Batch Validation", "CreateBatch" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": true, "description": "The ID of the organization to use for this request. Required for all authenticated endpoints.", "schema": {}, "example": "123" } ], "requestBody": { "required": true, "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/CreateBatchRequest" } } } }, "responses": { "422": { "description": "Invalid CSV file", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Invalid request", "message": "CSV file must contain an 'email' column." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Invalid request" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "201": { "description": "Batch created successfully", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "value": { "id": 123, "name": "My Contact List", "status": "pending", "total_count": 1000, "message": "Batch validation started" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "total_count": { "type": "integer" }, "message": { "type": "string", "const": "Batch validation started" } }, "required": [ "id", "name", "status", "total_count", "message" ] } } } }, "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "No team selected" } }, "required": [ "error" ] } } } }, "403": { "description": "Token lacks permission", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Forbidden", "message": "Token does not have permission to create batch validations." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "const": "Token does not have permission to create batch validations." } }, "required": [ "error", "message" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/validate\/batch\/{id}": { "get": { "operationId": "get-batch", "description": "Retrieve the current status and statistics of a batch validation job.\nPoll this endpoint to track progress of your batch validation.\n\n**Required Permission:** `validate:batch`\n\n**Rate Limit:** 60 requests per minute", "summary": "Get Batch Status", "tags": [ "Batch Validation", "GetBatch" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "X-Organization-ID", "in": "header", "required": true, "description": "The ID of the organization to use for this request. Required for all authenticated endpoints.", "schema": {}, "example": "123" } ], "responses": { "200": { "description": "Batch status", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "value": { "id": 123, "name": "My Contact List", "status": "processing", "total_count": 1000, "processed_count": 450, "valid_count": 380, "invalid_count": 50, "risky_count": 15, "unknown_count": 5, "credits_used": 450, "progress": 45, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:35:00Z" }, "summary": null, "description": null, "externalValue": null } ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "total_count": { "type": "integer" }, "processed_count": { "type": "integer" }, "valid_count": { "type": "integer" }, "invalid_count": { "type": "integer" }, "risky_count": { "type": "integer" }, "unknown_count": { "type": "integer" }, "credits_used": { "type": "integer" }, "progress": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "status", "total_count", "processed_count", "valid_count", "invalid_count", "risky_count", "unknown_count", "credits_used", "progress", "created_at", "updated_at" ] } } } }, "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "No team selected" } }, "required": [ "error" ] } } } }, "403": { "description": "Token lacks permission", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Forbidden", "message": "Token does not have permission to access batch validations." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "const": "Token does not have permission to access batch validations." } }, "required": [ "error", "message" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "Batch not found", "content": { "application\/json": { "schema": { "type": "string", "examples": [ { "value": { "message": "No query results for model" }, "summary": null, "description": null, "externalValue": null } ] } } } } } } }, "\/validate\/batch\/{id}\/download": { "get": { "operationId": "download-batch", "description": "Download the CSV results file for a completed batch validation.\nOnly available after the batch status is 'completed'.\n\n**Required Permission:** `validate:batch`\n\n**Rate Limit:** 60 requests per minute", "summary": "Download Batch Results", "tags": [ "Batch Validation", "GetBatch" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "X-Organization-ID", "in": "header", "required": true, "description": "The ID of the organization to use for this request. Required for all authenticated endpoints.", "schema": {}, "example": "123" } ], "responses": { "404": { "description": "Results not available", "content": { "application\/json": { "schema": { "examples": [ { "value": { "error": "Results not available", "message": "Batch is not yet completed or results file not found." }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "error": { "type": "string", "const": "Results not available" }, "message": { "type": "string", "const": "Results file not found." } }, "required": [ "error", "message" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Results not available" }, "message": { "type": "string", "const": "Batch is not yet completed or results file not found." } }, "required": [ "error", "message" ] } ] } } } }, "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "No team selected" } }, "required": [ "error" ] } } } }, "403": { "description": "Token lacks permission", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Forbidden", "message": "Token does not have permission to download batch results." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "const": "Token does not have permission to download batch results." } }, "required": [ "error", "message" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "200": { "description": "CSV file download", "content": { "text\/csv": { "schema": { "type": "string" } } } } } } }, "\/credits\/balance": { "get": { "operationId": "get-credits", "description": "Retrieve your current credit balance and monthly allowance usage.\nUse this endpoint to check available credits before making validations.\n\n**Required Permission:** `credits:read`\n\n**Rate Limit:** 60 requests per minute", "summary": "Get Credit Balance", "tags": [ "Credits", "CreditBalance" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": true, "description": "The ID of the organization to use for this request. Required for all authenticated endpoints.", "schema": {}, "example": "123" } ], "responses": { "200": { "description": "Credit balance", "content": { "application\/json": { "schema": { "examples": [ { "value": { "balance": 5000, "monthly_allowance_used": 250, "monthly_allowance_reset_at": "2024-02-01T00:00:00Z" }, "summary": null, "description": null, "externalValue": null } ], "anyOf": [ { "type": "object", "properties": { "balance": { "type": "integer" }, "monthly_allowance_used": { "type": "integer" }, "monthly_allowance_reset_at": { "type": "string" } }, "required": [ "balance", "monthly_allowance_used", "monthly_allowance_reset_at" ] }, { "type": "object", "properties": { "balance": { "type": "integer" }, "monthly_allowance_used": { "type": "integer" }, "monthly_allowance_reset_at": { "type": "null" } }, "required": [ "balance", "monthly_allowance_used", "monthly_allowance_reset_at" ] } ] } } } }, "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "No team selected" } }, "required": [ "error" ] } } } }, "403": { "description": "Token lacks permission", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Forbidden", "message": "Token does not have permission to view credits." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "const": "Token does not have permission to view credits." } }, "required": [ "error", "message" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/validate\/single": { "post": { "operationId": "validate-single", "description": "Validates a single email address and returns detailed information about its deliverability.\nThis endpoint consumes 1 credit per validation (0 if cached).\n\n**Required Permission:** `validate:single`\n\n**Rate Limit:** 60 requests per minute", "summary": "Validate Single Email", "tags": [ "Email Validation", "ValidateSingle" ], "parameters": [ { "name": "X-Organization-ID", "in": "header", "required": true, "description": "The ID of the organization to use for this request. Required for all authenticated endpoints.", "schema": {}, "example": "123" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ValidateSingleRequest" } } } }, "responses": { "402": { "description": "Insufficient credits", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Insufficient credits", "message": "You need at least 1 credit to validate an email." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Insufficient credits" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "200": { "description": "Valid email response", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "value": { "email": "john@example.com", "status": "valid", "confidence": 95, "mx_found": true, "smtp_valid": true, "is_disposable": false, "is_catch_all": false, "is_role_account": false, "from_cache": false, "credits_used": 1, "result": [] }, "summary": null, "description": null, "externalValue": null } ], "properties": { "email": { "type": "string" }, "status": { "type": "string" }, "confidence": { "type": "integer" }, "mx_found": { "type": "boolean" }, "smtp_valid": { "type": [ "boolean", "null" ] }, "is_disposable": { "type": "boolean" }, "is_catch_all": { "type": [ "boolean", "null" ] }, "is_role_account": { "type": "boolean" }, "from_cache": { "type": "boolean" }, "credits_used": { "type": "integer" }, "result": { "type": [ "array", "null" ], "items": {} } }, "required": [ "email", "status", "confidence", "mx_found", "smtp_valid", "is_disposable", "is_catch_all", "is_role_account", "from_cache", "credits_used", "result" ] } } } }, "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "No team selected" } }, "required": [ "error" ] } } } }, "403": { "description": "Token lacks permission", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "value": { "error": "Forbidden", "message": "Token does not have permission to validate single emails." }, "summary": null, "description": null, "externalValue": null } ], "properties": { "error": { "type": "string", "const": "Forbidden" }, "message": { "type": "string", "const": "Token does not have permission to validate single emails." } }, "required": [ "error", "message" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "description": "API tokens can be generated from your [Dashboard](\/dashboard\/api-tokens). Include the token in the Authorization header as `Bearer YOUR_API_TOKEN`.", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "CreateBatchRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "file": { "type": "string", "format": "binary", "contentMediaType": "application\/octet-stream", "maxLength": 102400 } }, "required": [ "name", "file" ], "title": "CreateBatchRequest" }, "ValidateSingleRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 } }, "required": [ "email" ], "title": "ValidateSingleRequest" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }