contacts_api_recipients.json

{
    "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.json#/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.json#/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.json#/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.json#/global_error_response_schema"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "errors": [
                                            {
                                                "field": null,
                                                "message": "authorization required"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "security": [
                {
                    "Authorization": []
                }
            ]
        },
        "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.json#/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.json#/contactdb_recipient_response"
                            }
                        }
                    }
                },
                "400": {
                    "description": "\"\" : \"Returned if request body is not valid json\"",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "../../components/schemas.json#/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.json#/global_error_response_schema"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "errors": [
                                            {
                                                "field": null,
                                                "message": "authorization required"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "security": [
                {
                    "Authorization": []
                }
            ]
        },
        "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.json#/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.json#/global_error_response_schema"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "errors": [
                                            {
                                                "message": "No recipient ids provided"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                },
                "401": {
                    "description": "",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "../../components/schemas.json#/global_error_response_schema"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "errors": [
                                            {
                                                "field": null,
                                                "message": "authorization required"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "security": [
                {
                    "Authorization": []
                }
            ]
        },
        "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.json#/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.json#/global_error_response_schema"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "errors": [
                                            {
                                                "field": null,
                                                "message": "authorization required"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "security": [
                {
                    "Authorization": []
                }
            ]
        }
    },
    "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.json#/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": []
                }
            ]
        }
    },
    "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.json#/trait_onBehalfOfSubuser_on-behalf-of"
                }
            ],
            "responses": {
                "200": {
                    "description": "",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "../../components/schemas.json#/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.json#/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": []
                }
            ]
        },
        "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.json#/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.json#/global_error_response_schema"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "errors": [
                                            {
                                                "field": null,
                                                "message": "recipient not found"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                },
                "401": {
                    "description": "",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "../../components/schemas.json#/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.json#/global_error_response_schema"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "errors": [
                                            {
                                                "field": null,
                                                "message": "recipient_id is not valid"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "security": [
                {
                    "Authorization": []
                }
            ]
        }
    },
    "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.json#/trait_onBehalfOfSubuser_on-behalf-of"
                }
            ],
            "responses": {
                "200": {
                    "description": "",
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "lists": {
                                        "type": "array",
                                        "items": {
                                            "$ref": "../../components/schemas.json#/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.json#/global_error_response_schema"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "errors": [
                                            {
                                                "field": null,
                                                "message": "recipient ID is invalid"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                },
                "401": {
                    "description": "",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "../../components/schemas.json#/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.json#/global_error_response_schema"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "errors": [
                                            {
                                                "field": null,
                                                "message": "recipient id not found"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "security": [
                {
                    "Authorization": []
                }
            ]
        }
    },
    "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.json#/trait_onBehalfOfSubuser_on-behalf-of"
                }
            ],
            "responses": {
                "200": {
                    "description": "",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "../../components/schemas.json#/contactdb_recipient_count"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "recipient_count": 1234
                                    }
                                }
                            }
                        }
                    }
                },
                "401": {
                    "description": "",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "../../components/schemas.json#/global_error_response_schema"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "errors": [
                                            {
                                                "field": null,
                                                "message": "authorization required"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "security": [
                {
                    "Authorization": []
                }
            ]
        }
    },
    "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.json#/trait_onBehalfOfSubuser_on-behalf-of"
                }
            ],
            "responses": {
                "200": {
                    "description": "",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "../../components/schemas.json#/contactdb_recipient_count"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "recipient_count": 1234
                                    }
                                }
                            }
                        }
                    }
                },
                "401": {
                    "description": "",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "../../components/schemas.json#/global_error_response_schema"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "errors": [
                                            {
                                                "field": null,
                                                "message": "authorization required"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "security": [
                {
                    "Authorization": []
                }
            ]
        }
    },
    "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.json#/trait_onBehalfOfSubuser_on-behalf-of"
                }
            ],
            "responses": {
                "200": {
                    "description": "",
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "recipients": {
                                        "type": "array",
                                        "items": {
                                            "$ref": "../../components/schemas.json#/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.json#/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.json#/global_error_response_schema"
                            },
                            "examples": {
                                "response": {
                                    "value": {
                                        "errors": [
                                            {
                                                "field": null,
                                                "message": "authorization required"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "security": [
                {
                    "Authorization": []
                }
            ]
        },
        "post": {
            "operationId": "POST_contactdb-recipients-search",
            "summary": "Search recipients",
            "tags": [
                "Contacts API - Recipients"
            ],
            "description": "<p>\n  Search using segment conditions without actually creating a segment.\n  Body contains a JSON object with <code>conditions</code>, a list of conditions as described below, and an optional <code>list_id</code>, which is a valid list ID for a list to limit the search on.\n</p>\n\n<p>\n  Valid operators for create and update depend on the type of the field for which you are searching.\n</p>\n\n<ul>\n  <li>Dates:\n    <ul>\n      <li>\"eq\", \"ne\", \"lt\" (before), \"gt\" (after)\n        <ul>\n          <li>You may use MM/DD/YYYY for day granularity or an epoch for second granularity.</li>\n        </ul>\n      </li>\n      <li>\"empty\", \"not_empty\"</li>\n      <li>\"is within\"\n        <ul>\n          <li>You may use an <a href=\"https://en.wikipedia.org/wiki/ISO_8601\">ISO 8601 date format</a> or the # of days.</li>\n        </ul>\n      </li>\n    </ul>\n  </li>\n  <li>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\"</li>\n  <li>Numbers: \"eq\", \"lt\", \"gt\", \"empty\", \"not_empty\"</li>\n  <li>Email Clicks and Opens: \"eq\" (opened), \"ne\" (not opened)</li>\n</ul>\n\n<p>\n  Field values must all be a string.\n</p>\n\n<p>\n  Search conditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either <code>clicks.campaign_identifier</code> or <code>opens.campaign_identifier</code>.\n  The condition value should be a string containing the id of a completed campaign.\n</p>\n\n<p>\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</p>",
            "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.json#/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": []
                }
            ]
        }
    }
}