Batch Operations

Use batch operations to complete multiple operations with a single call.

Available methods

    • POST /batches Start a batch operation

      Start a batch operation

      POST /batches

      Begin processing a batch operations request.

      Request body parameters

      operations Type: Array Title: Operations List Read only: false An array of objects that describes operations to perform.
      Show properties
      method Type: String Title: HTTP Method Read only: false The HTTP method to use for the operation.
      Possible Values:
      • GET
      • POST
      • PUT
      • PATCH
      path Type: String Title: Path Read only: false The relative path to use for the operation.
      params Type: Object Title: URL params Read only: false Any URL params to use, only applies to GET operations.
      body Type: String Title: Body Read only: false A string containing the JSON body to use with the request.
      operation_id Type: String Title: Operation ID Read only: false An optional client-supplied id returned with the operation results.

      Response body parameters

      id Type: String Title: Batch ID Read only: true A string that uniquely identifies this batch request.
      status Type: String Title: Status Read only: true The status of the batch call. Learn more about how batch operations are processed.
      Possible Values:
      • pending
      • preprocessing
      • started
      • finalizing
      • finished
      total_operations Type: Integer Title: Total Operations Read only: true The total number of operations to complete as part of this batch request. For GET requests requiring pagination, each page counts as a separate operation.
      finished_operations Type: Integer Title: Finished Operations Read only: true The number of completed operations. This includes operations that returned an error.
      errored_operations Type: Integer Title: Error Operations Read only: true The number of completed operations that returned an error.
      submitted_at Type: String Title: Submitted At Read only: true The date and time when the server received the batch request.
      completed_at Type: String Title: Completed At Read only: true The date and time when all operations in the batch request completed.
      response_body_url Type: String Title: Response Body URL Read only: true The URL of the gzipped archive of the results of all the operations.
      _links Type: Array Title: Links Read only: true A list of link types and descriptions for the API schema documents.
      Show properties
      rel Type: String Title: Rel Read only: true As with an HTML ‘rel’ attribute, this describes the type of link.
      href Type: String Title: Href Read only: true This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
      method Type: String Title: Method Read only: true The HTTP method that should be used when accessing the URL defined in ‘href’.
      Possible Values:
      • GET
      • POST
      • PUT
      • PATCH
      • DELETE
      • OPTIONS
      • HEAD
      targetSchema Type: String Title: Target Schema Read only: true For GETs, this is a URL representing the schema that the response should conform to.
      schema Type: String Title: Schema Read only: true For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.

      Example request

      
      curl --request POST \
      --url 'https://usX.api.mailchimp.com/3.0/batches' \
      --user 'anystring:apikey' \
      --header 'content-type: application/json' \
      --data '{"operations" : [{"method" : "POST","path" : "lists/624ea08019/members", "body": "{\"email_address\":\"freddie@mailchimp.com\", \"status\":\"subscribed\"}"}, {"method" : "POST","path" : "lists/624ea08019/members", "body": "{\"email_address\":\"freddy@mailchimp.com\", \"status\":\"subscribed\"}"}, {"method" : "POST","path" : "lists/624ea08019/members", "body": "{\"email_address\":\"fred@mailchimp.com\", \"status\":\"subscribed\"}"}, {"method" : "POST","path" : "lists/624ea08019/members", "body": "{\"email_address\":\"frederick@mailchimp.com\", \"status\":\"subscribed\"}"}]}' \
      --include
                                      

      Example response

      
      HTTP/1.1 200 OK
      Server: nginx
      Date: Thu, 12 May 2016 17:43:33 GMT
      Content-Type: application/json; charset=utf-8
      Content-Length: 619
      Connection: keep-alive
      Vary: Accept-Encoding
      X-Request-Id: 2a5f22fd-5456-4d8f-801e-3f8aa86d3e9c
      Link: <https://api.mailchimp.com/schema/3.0/Batches/Instance.json>; rel="describedBy"
      
      {
        "id": "8b2428d747",
        "status": "pending",
        "total_operations": 0,
        "finished_operations": 0,
        "errored_operations": 0,
        "submitted_at": "2016-05-12T17:43:32+00:00",
        "completed_at": "",
        "response_body_url": "",
        "_links": [
          {
            "rel": "parent",
            "href": "https://usX.api.mailchimp.com/3.0/batches",
            "method": "GET",
            "targetSchema": "https://api.mailchimp.com/schema/3.0/Batches/Collection.json",
            "schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Batches.json"
          },
          {
            "rel": "self",
            "href": "https://usX.api.mailchimp.com/3.0/batches/8b2428d747",
            "method": "GET",
            "targetSchema": "https://api.mailchimp.com/schema/3.0/Batches/Instance.json"
          }
        ]
      }
                                      

      Error response

      type Type: String Title: Problem Type Read only: false An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
      title Type: String Title: Error Title Read only: false A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
      status Type: Integer Title: HTTP Status Code Read only: false The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
      detail Type: String Title: Error Message Read only: false A human-readable explanation specific to this occurrence of the problem. Learn more about errors.
      instance Type: String Title: Instance ID Read only: false A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
    • GET /batches Get a list of batch requests
      GET /batches/{batch_id} Get the status of a batch operation request

      Get a list of batch requests

      GET /batches

      Get a summary of batch requests that have been made.

      Query string parameters

      fields Type: Array Title: Fields Read only: false A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
      exclude_fields Type: Array Title: Exclude Fields Read only: false A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.
      count Type: Integer Title: Count Read only: true The number of records to return. Default value is 10.
      offset Type: Integer Title: Offset Read only: false The number of records from a collection to skip. Iterating over large collections with this parameter can be slow. Default value is 0.

      Response body parameters

      batches Type: Array Title: Batches Read only: false An array of objects representing batch calls.
      Show properties
      id Type: String Title: Batch ID Read only: true A string that uniquely identifies this batch request.
      status Type: String Title: Status Read only: true The status of the batch call. Learn more about how batch operations are processed.
      Possible Values:
      • pending
      • preprocessing
      • started
      • finalizing
      • finished
      total_operations Type: Integer Title: Total Operations Read only: true The total number of operations to complete as part of this batch request. For GET requests requiring pagination, each page counts as a separate operation.
      finished_operations Type: Integer Title: Finished Operations Read only: true The number of completed operations. This includes operations that returned an error.
      errored_operations Type: Integer Title: Error Operations Read only: true The number of completed operations that returned an error.
      submitted_at Type: String Title: Submitted At Read only: true The date and time when the server received the batch request.
      completed_at Type: String Title: Completed At Read only: true The date and time when all operations in the batch request completed.
      response_body_url Type: String Title: Response Body URL Read only: true The URL of the gzipped archive of the results of all the operations.
      _links Type: Array Title: Links Read only: true A list of link types and descriptions for the API schema documents.
      Show properties
      rel Type: String Title: Rel Read only: true As with an HTML ‘rel’ attribute, this describes the type of link.
      href Type: String Title: Href Read only: true This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
      method Type: String Title: Method Read only: true The HTTP method that should be used when accessing the URL defined in ‘href’.
      Possible Values:
      • GET
      • POST
      • PUT
      • PATCH
      • DELETE
      • OPTIONS
      • HEAD
      targetSchema Type: String Title: Target Schema Read only: true For GETs, this is a URL representing the schema that the response should conform to.
      schema Type: String Title: Schema Read only: true For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
      total_items Type: Integer Title: Item Count Read only: false The total number of items matching the query regardless of pagination.
      _links Type: Array Title: Links Read only: true A list of link types and descriptions for the API schema documents.
      Show properties
      rel Type: String Title: Rel Read only: true As with an HTML ‘rel’ attribute, this describes the type of link.
      href Type: String Title: Href Read only: true This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
      method Type: String Title: Method Read only: true The HTTP method that should be used when accessing the URL defined in ‘href’.
      Possible Values:
      • GET
      • POST
      • PUT
      • PATCH
      • DELETE
      • OPTIONS
      • HEAD
      targetSchema Type: String Title: Target Schema Read only: true For GETs, this is a URL representing the schema that the response should conform to.
      schema Type: String Title: Schema Read only: true For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.

      Example request

      
      curl --request GET \
      --url 'https://usX.api.mailchimp.com/3.0/batches' \
      --user 'anystring:apikey' \
      --include
                                      

      Example response

      
      HTTP/1.1 200 OK
      Server: nginx
      Date: Thu, 12 May 2016 17:44:33 GMT
      Content-Type: application/json; charset=utf-8
      Content-Length: 1397
      Connection: keep-alive
      Vary: Accept-Encoding
      X-Request-Id: 146919f6-6ae4-401f-953c-a316eb9d3fd5
      Link: <https://api.mailchimp.com/schema/3.0/Batches/Collection.json>; rel="describedBy"
      
      {
        "batches": [
          {
            "id": "8b2428d747",
            "status": "finished",
            "total_operations": 4,
            "finished_operations": 4,
            "errored_operations": 0,
            "submitted_at": "2016-05-12T17:43:32+00:00",
            "completed_at": "2016-05-12T17:43:42+00:00",
            "response_body_url": "https://mailchimp-api-batch.s3.amazonaws.com/8b2428d747-response.tar.gz?AWSAccessKeyId=AKIAJWOH5BECJQZIEWNQ&Expires=1463075673&Signature=wiP0TZ7J9S52LvCUTWEvexGbldU%3D",
            "_links": [
              {
                "rel": "parent",
                "href": "https://usX.api.mailchimp.com/3.0/batches",
                "method": "GET",
                "targetSchema": "https://api.mailchimp.com/schema/3.0/Batches/Collection.json",
                "schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Batches.json"
              },
              {
                "rel": "self",
                "href": "https://usX.api.mailchimp.com/3.0/batches/8b2428d747",
                "method": "GET",
                "targetSchema": "https://api.mailchimp.com/schema/3.0/Batches/Instance.json"
              }
            ]
          }
        ],
        "total_items": 1,
        "_links": [
          {
            "rel": "parent",
            "href": "https://usX.api.mailchimp.com/3.0/",
            "method": "GET",
            "targetSchema": "https://api.mailchimp.com/schema/3.0/Root.json"
          },
          {
            "rel": "self",
            "href": "https://usX.api.mailchimp.com/3.0/batches",
            "method": "GET",
            "targetSchema": "https://api.mailchimp.com/schema/3.0/Batches/Collection.json",
            "schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Batches.json"
          },
          {
            "rel": "create",
            "href": "https://usX.api.mailchimp.com/3.0/batches",
            "method": "POST",
            "schema": "https://api.mailchimp.com/schema/3.0/Batches/Create.json"
          }
        ]
      }
                                      

      Error response

      type Type: String Title: Problem Type Read only: false An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
      title Type: String Title: Error Title Read only: false A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
      status Type: Integer Title: HTTP Status Code Read only: false The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
      detail Type: String Title: Error Message Read only: false A human-readable explanation specific to this occurrence of the problem. Learn more about errors.
      instance Type: String Title: Instance ID Read only: false A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.

      Get the status of a batch operation request

      GET /batches/{batch_id}

      Get the status of a batch request.

      Path parameters

      batch_id The unique id for the batch operation.

      Query string parameters

      fields Type: Array Title: Fields Read only: false A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
      exclude_fields Type: Array Title: Exclude Fields Read only: false A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.

      Response body parameters

      id Type: String Title: Batch ID Read only: true A string that uniquely identifies this batch request.
      status Type: String Title: Status Read only: true The status of the batch call. Learn more about how batch operations are processed.
      Possible Values:
      • pending
      • preprocessing
      • started
      • finalizing
      • finished
      total_operations Type: Integer Title: Total Operations Read only: true The total number of operations to complete as part of this batch request. For GET requests requiring pagination, each page counts as a separate operation.
      finished_operations Type: Integer Title: Finished Operations Read only: true The number of completed operations. This includes operations that returned an error.
      errored_operations Type: Integer Title: Error Operations Read only: true The number of completed operations that returned an error.
      submitted_at Type: String Title: Submitted At Read only: true The date and time when the server received the batch request.
      completed_at Type: String Title: Completed At Read only: true The date and time when all operations in the batch request completed.
      response_body_url Type: String Title: Response Body URL Read only: true The URL of the gzipped archive of the results of all the operations.
      _links Type: Array Title: Links Read only: true A list of link types and descriptions for the API schema documents.
      Show properties
      rel Type: String Title: Rel Read only: true As with an HTML ‘rel’ attribute, this describes the type of link.
      href Type: String Title: Href Read only: true This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
      method Type: String Title: Method Read only: true The HTTP method that should be used when accessing the URL defined in ‘href’.
      Possible Values:
      • GET
      • POST
      • PUT
      • PATCH
      • DELETE
      • OPTIONS
      • HEAD
      targetSchema Type: String Title: Target Schema Read only: true For GETs, this is a URL representing the schema that the response should conform to.
      schema Type: String Title: Schema Read only: true For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.

      Example request

      
      curl --request GET \
      --url 'https://usX.api.mailchimp.com/3.0/batches/8b2428d747' \
      --user 'anystring:apikey' \
      --include
                                      

      Example response

      
      HTTP/1.1 200 OK
      Server: nginx
      Date: Thu, 12 May 2016 17:44:57 GMT
      Content-Type: application/json; charset=utf-8
      Content-Length: 816
      Connection: keep-alive
      Vary: Accept-Encoding
      X-Request-Id: c6991c2d-fd5b-4b96-b440-ce2db7e94ff3
      Link: <https://api.mailchimp.com/schema/3.0/Batches/Instance.json>; rel="describedBy"
      
      {
        "id": "8b2428d747",
        "status": "finished",
        "total_operations": 4,
        "finished_operations": 4,
        "errored_operations": 0,
        "submitted_at": "2016-05-12T17:43:32+00:00",
        "completed_at": "2016-05-12T17:43:42+00:00",
        "response_body_url": "https://mailchimp-api-batch.s3.amazonaws.com/8b2428d747-response.tar.gz?AWSAccessKeyId=AKIAJWOH5BECJQZIEWNQ&Expires=1463075697&Signature=9Mva8uTbY56CIu3nywGcOgM%2FH%2FI%3D",
        "_links": [
          {
            "rel": "parent",
            "href": "https://usX.api.mailchimp.com/3.0/batches",
            "method": "GET",
            "targetSchema": "https://api.mailchimp.com/schema/3.0/Batches/Collection.json",
            "schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Batches.json"
          },
          {
            "rel": "self",
            "href": "https://usX.api.mailchimp.com/3.0/batches/8b2428d747",
            "method": "GET",
            "targetSchema": "https://api.mailchimp.com/schema/3.0/Batches/Instance.json"
          }
        ]
      }
                                      

      Error response

      type Type: String Title: Problem Type Read only: false An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
      title Type: String Title: Error Title Read only: false A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
      status Type: Integer Title: HTTP Status Code Read only: false The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
      detail Type: String Title: Error Message Read only: false A human-readable explanation specific to this occurrence of the problem. Learn more about errors.
      instance Type: String Title: Instance ID Read only: false A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.
    • DELETE /batches/{batch_id} Delete a batch request and stop if from processing further.

      Delete a batch request and stop if from processing further.

      DELETE /batches/{batch_id}

      Stops a batch request from running. Since only one batch request is run at a time, this can be used to cancel a long running request. The results of any completed operations will not be available after this call.

      Path parameters

      batch_id The unique id for the batch operation.

      Error response

      type Type: String Title: Problem Type Read only: false An absolute URI that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.
      title Type: String Title: Error Title Read only: false A short, human-readable summary of the problem type. It shouldn’t change based on the occurrence of the problem, except for purposes of localization.
      status Type: Integer Title: HTTP Status Code Read only: false The HTTP status code (RFC2616, Section 6) generated by the origin server for this occurrence of the problem.
      detail Type: String Title: Error Message Read only: false A human-readable explanation specific to this occurrence of the problem. Learn more about errors.
      instance Type: String Title: Instance ID Read only: false A string that identifies this specific occurrence of the problem. Please provide this ID when contacting support.