openapi: 3.0.0 info: version: 'v1.0.0' title: CloseAlert Reporting API description: | **Versions** - [v1.0.0](/v1.0.0) - [v2.0.0](/v2.0.0) # Introduction An API to get CloseAlert responses into your own database.The API is only available over the **HTTPS** protocol. This API is RESTful and will only return JSON. # Security We have different security measurements in place to make sure this API is safe for you to use: - Token based authentication - Tokens can expire - IP whitelisting - API only accessible over HTTPS - User / IP is blocked after too many failed authentication attempts # Authentication For authentication you must use a JSON WEB Token [JWT] ([RFC7519](https://tools.ietf.org/html/rfc7519)). These can be generated only in our application. This is done by doing the following steps: - 1. Go to our [application](https://app.closealert.com/) - 2. Go to **Settings** - 3. Go to **API Access** - 4. Click on **Generate API Access Token** - 5. Fill in name and in how many days the token must expire. (Choose 0 if you don't want it to expire) - 6. Copy the generated token and safe it in a safe place. **Note**: This key is only provided once. In this overview you will also see how many time the different keys are used and when the last time was they were used. You must use the generated JWT by sending it with the **Authentication header** each request. For example, your JWT is `super.safe.token`, you must add the following header: *-H Authorization: Bearer super.safe.token'* # IP Whitelisting For authentication to work, you will only need to whitelist the IP addresses of your server(s) that will do the requests to our servers. This is done by doing the following steps: - 1. Go to our [application](https://app.closealert.com/) - 2. Go to **Settings** - 3. Go to **API Access** - 4. Scroll to **Whitelisted IP's** - 5. Add your IP address(es). **Note:** When no IP addresses set, the API is not accessible. # Ratelimiting To prevent the servers to be accessed too many times my one customer for a small period, the API is rate limited. When accessed too many times a `429` response is returned. # Limitations To prevent that our servers must return too much data at one time, it's only possible to get data of a period no longer than 10 days. It will also not return more than X TODO results per request. When not all the required data is returned at once, you can use the *meta* object that is also returned each request. This will give you info about pagination. servers: - url: 'http://api.closealert.local:8080/v1.0.0/' paths: /{project_key}/form_responses: parameters: - in: path name: project_key required: true schema: type: string description: the key of your project example: e.g. 'company.com' get: security: - bearerAuth: [] summary: GET form_responses description: > Returns responses from CloseAlert that are received. parameters: - name: form_id in: query description: To filter on a specific form required: false style: form schema: type: integer - name: since in: query description: Responses received since a specific date-time ([ISO8601](https://en.wikipedia.org/wiki/ISO_8601)) example: '2018-12-12T09:35:05+00:00' required: false style: form schema: type: string format: date-time - name: until in: query description: Responses received until a specific date-time ([ISO8601](https://en.wikipedia.org/wiki/ISO_8601)) example: '2018-12-12T09:35:05+00:00' required: false style: form schema: type: string format: date-time - name: per_page in: query description: Maximum results per page example: 20 required: false style: form schema: type: integer - name: page in: query description: The page number example: 1 required: false schema: type: integer - name: mailing_id in: query description: The id of the mailing to filter on required: false schema: type: integer - name: group_id in: query description: The id of the group to filter on required: false schema: type: integer responses: '200': description: successful operation content: application/json: schema: type: object properties: form_responses: type: array items: $ref: "#/components/schemas/form_response" meta: $ref: "#/components/schemas/meta" example: form_responses: - id: 1 created_at: '2014-03-17T17:22:10.055-07:00' email: 'peter@closealert.com' mail_url: 'http://www.closealert.com' user_agent: 'Mozilla/5.0 (Intel Mac OS X 10.9' followed_up: true merge_tags: - age: 10 gender: male form: id: 34 form_type: email-satisfaction, name: 'Email satisfaction form' mailing: id: 42 name: 'Email satisfaction mailing' group: id: 44 name: 'Email satisfaction group' answers: - question: 'What do you think of this email?' question_type: 'sentiment' question_index: 1 response_value: 1 scale: 2 - question: 'Why are you positive?' question_type: 'comment' question_index: 1.1 response_value: 'I love the articles in this email' meta: page: 0 page_number: 1 total_pages: 1 '422': description: Validation failed content: application/json: schema: type: object properties: error: $ref: "#/components/schemas/error" example: error: description: "Validation failed" code: 422 attributes: date_from: invalid filter '429': description: Too many requests '403': description: Authentication failed '504': description: Took server too long to respond components: schemas: form_response: properties: id: type: integer description: the id of the form_response created_at: type: string format: date-time description: the time stamp (ISO8601) this form_response was received email: type: string description: the email address of the recipient mail_url: type: string description: the mail_url of the recipient user_agent: type: string description: the user agent of the recipient followed_up: type: boolean description: whether a follow up mail was send by CloseAlert based on given answers merge_tags: type: object description: the merge tags that were send by the ESP form: type: object description: the form this response was received on properties: id: type: integer description: the id of the form form_type: type: string description: the type of the form the response was received on name: type: string description: the name of the form mailing: type: object description: the mailing this response was received on properties: id: type: integer description: the id of the mailing name: type: string description: the name of the mailing group: type: object description: the group the mailing is in (either direct or nested) properties: id: type: integer description: the id of the group name: type: string description: the name of the group answer: type: array description: the given answers of the recipient items: type: object description: answer object properties: question: type: string description: the question that was asked question_type: type: string description: the type of the question question_index: type: integer description: The index of the question on received form response_value: type: string description: The given answer of the recipient on this question meta: properties: page: type: integer description: The page number per_page: type: integer description: Maximum results per page total_pages: type: integer description: The total number of pages error: properties: description: type: string description: The description of the error code: type: integer description: The error code attributes: type: object description: An object containing key-value pairs with key=attribute, value=description of error securitySchemes: bearerAuth: type: http scheme: bearer security: - bearerAuth: []