---
agentTools:
  projectIndex: https://developer.taskrabbit.com/llms.txt
---

# Book a Project Agreement

This endpoint completes the booking of a project on Taskrabbit with the Project ID, customer information, Taskrabbit’s Terms of Service & Privacy Policy Acceptance Indicator (Y/N), Description to be displayed with the project, and an optional Partner Order ID.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Taskrabbit Partner Platform API",
    "description": "Taskrabbit’s Partner API allows you to offer professional home services directly to your customers.\nWith simple endpoints for availability, pricing, and booking, you can embed Taskrabbit’s services into your checkout flow or post-purchase experience; no need for your users to leave your platform.\nThis API is designed for partners who want a lightweight, scalable way to add home services to their product offering.",
    "version": "2025-12"
  },
  "servers": [
    {
      "url": "https://{api_subdomain}.partner-platform.taskrabbit.com/2025-12",
      "description": "Partner Test Environment",
      "variables": {
        "api_subdomain": {
          "description": "Partner name",
          "default": "<your-subdomain>"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Project Booking APIs",
      "description": "APIs related to operate over project booking"
    }
  ],
  "paths": {
    "/projects/book": {
      "post": {
        "tags": [
          "Project Booking APIs"
        ],
        "summary": "Book a Project Agreement",
        "description": "This endpoint completes the booking of a project on Taskrabbit with the Project ID, customer information, Taskrabbit’s Terms of Service & Privacy Policy Acceptance Indicator (Y/N), Description to be displayed with the project, and an optional Partner Order ID.",
        "operationId": "projectBook",
        "requestBody": {
          "description": "Book a Project Agreement",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BookRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BookResponse"
                },
                "example": {
                  "status": 201,
                  "request_id": "550e8400-e29b-41d4-a716-446655440000",
                  "data": {
                    "project": {
                      "project_uuid": "6aa34486-b124-41ba-a411-69ee9438eb47",
                      "state": "booked",
                      "locale": "en-US",
                      "currency": "USD",
                      "parties": {
                        "service_provider_tenant_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                        "client_uuid": "ec547716-3641-437a-8671-15b2dcabcd51"
                      },
                      "location": {
                        "address": {
                          "line_1": "123 Main Street",
                          "line_2": "Apt 123",
                          "city": "New York",
                          "region": "New York",
                          "country": "USA",
                          "postal_code": "10019"
                        }
                      },
                      "pricing": {
                        "service_item_terms": [
                          {
                            "service_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                            "service_item_term_external_reference": "cart-line:12345",
                            "service_item_term_description": "Three-tier wooden rabbit hutch with plush cushions. Follow the instructions included in the packaging.",
                            "product_name": "Bunny's Dream House - Birch",
                            "product_external_reference": "abc-0014",
                            "total_amount": {
                              "cents": 1000,
                              "currency": "USD"
                            }
                          }
                        ],
                        "agreement_terms": {
                          "agreement_minimum_price": {
                            "cents": 1000,
                            "currency": "USD"
                          }
                        },
                        "total_amount": {
                          "cents": 1000,
                          "currency": "USD"
                        }
                      },
                      "target_start_time": "2024-06-11T20:00:00.000Z",
                      "agreement_metadata": {
                        "client_amount_charged_cents": 10000,
                        "client_accepted_taskrabbit_policy": true,
                        "agreement_external_reference": "partner-order-12345"
                      }
                    },
                    "client_amount_charged_cents": {
                      "cents": 1000,
                      "currency": "USD"
                    },
                    "client_accepted_taskrabbit_policy": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InvalidBookRequest"
                    },
                    {
                      "$ref": "#/components/schemas/ValidationError"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SuccessResponse": {
        "description": "This defines a common response structure for all APIs",
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "examples": [
              201
            ]
          },
          "request_id": {
            "type": "string",
            "format": "uuid",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000"
            ]
          },
          "data": {
            "type": "object"
          }
        }
      },
      "ErrorResponse": {
        "description": "This defines a commmon response structure for all errors",
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "examples": [
              400
            ]
          },
          "request_id": {
            "type": "string",
            "format": "uuid",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000"
            ]
          },
          "error": {
            "type": "object",
            "properties": {
              "uuid": {
                "type": "string",
                "format": "uuid",
                "examples": [
                  "550e8400-e29b-41d4-a716-446655440000"
                ]
              },
              "message": {
                "type": "string"
              },
              "code": {
                "type": "string"
              }
            }
          }
        }
      },
      "BookRequest": {
        "description": "Information given to create a booking.",
        "type": "object",
        "required": [
          "client",
          "project_uuid",
          "client_amount_charged_cents",
          "client_accepted_taskrabbit_policy",
          "agreement_external_reference"
        ],
        "properties": {
          "client": {
            "$ref": "#/components/schemas/Client"
          },
          "project_uuid": {
            "description": "The unique identifier for a Project Agreement created by the projects/bid request.",
            "type": "string",
            "format": "uuid"
          },
          "client_amount_charged_cents": {
            "description": "The total amount a Partner charged for the Project",
            "type": "integer",
            "examples": [
              10000
            ]
          },
          "client_accepted_taskrabbit_policy": {
            "$ref": "#/components/schemas/ClientAcceptedTaskrabbitPolicy"
          },
          "agreement_external_reference": {
            "type": "string",
            "description": "**REQUIRED** Partner provided transaction information for reconciliation and cross-referencing.\n\nThis field is essential for:\n- Invoice reconciliation between partner and Taskrabbit systems\n- Customer service lookups and support\n- Cross-referencing orders across partner platforms\n\nExamples:\n- Partner order number: \"ORDER-12345\"\n- Transaction ID: \"TXN-ABC123\"\n- Invoice reference: \"INV-2024-001\"",
            "examples": [
              "ORDER-12345",
              "TXN-ABC123",
              "INV-2024-001"
            ]
          },
          "agreement_accounting_reference": {
            "type": "string",
            "description": "Optional partner provided accounting reference for financial reconciliation (e.g. a purchase order number or cost center code).",
            "examples": [
              "PO-98765",
              "CC-MARKETING-2024"
            ]
          }
        }
      },
      "BookResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "project": {
                    "$ref": "#/components/schemas/Project"
                  },
                  "client_amount_charged_cents": {
                    "description": "The amount that the client was charged at booking time.",
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/Price"
                      }
                    ]
                  },
                  "client_accepted_taskrabbit_policy": {
                    "$ref": "#/components/schemas/ClientAcceptedTaskrabbitPolicy"
                  }
                }
              }
            }
          }
        ]
      },
      "ClientAcceptedTaskrabbitPolicy": {
        "type": "boolean",
        "description": "Indicates whether clients accepted Taskrabbit Terms of Service and Privacy Policy."
      },
      "TargetStartTime": {
        "type": "string",
        "description": "The earliest time a Tasker can begin a project.",
        "format": "date-time",
        "examples": [
          "2024-06-11T20:00:00.000Z"
        ]
      },
      "Client": {
        "description": "This is the client information of who is having the services completed for.",
        "type": "object",
        "required": [
          "first_name",
          "last_name",
          "email"
        ],
        "properties": {
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "phone_number": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "idn-email"
          }
        }
      },
      "Project": {
        "type": "object",
        "properties": {
          "project_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "The unique identifier for a Project Agreement created by the projects/bid request.",
            "examples": [
              "6aa34486-b124-41ba-a411-69ee9438eb47"
            ]
          },
          "state": {
            "type": "string",
            "description": "Currently there two states. Draft is where there is a project agreement but the project has not been booked. Booked is where the project is booked.",
            "enum": [
              "draft",
              "booked"
            ]
          },
          "locale": {
            "type": "string",
            "description": "The locale for the transaction with the customer. NOTE As of version 1.0 only en-US is available.",
            "enum": [
              "en-US"
            ]
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "parties": {
            "$ref": "#/components/schemas/AgreementParties"
          },
          "location": {
            "$ref": "#/components/schemas/FullLocation"
          },
          "pricing": {
            "$ref": "#/components/schemas/AgreementPriceQuote"
          },
          "target_start_time": {
            "$ref": "#/components/schemas/TargetStartTime"
          },
          "agreement_metadata": {
            "$ref": "#/components/schemas/AgreementMetadata"
          }
        }
      },
      "AgreementParties": {
        "description": "The parties involved for a Project Agreement",
        "type": "object",
        "properties": {
          "service_provider_tenant_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "A partner's unique identifier"
          },
          "client_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "The client's unique identifier",
            "examples": [
              "ec547716-3641-437a-8671-15b2dcabcd51"
            ]
          }
        }
      },
      "AgreementMetadata": {
        "description": "Additional metadata associated with the project agreement, including partner-specific transaction details",
        "type": "object",
        "nullable": true,
        "properties": {
          "client_amount_charged_cents": {
            "type": "integer",
            "nullable": true,
            "description": "The total amount in cents that the partner charged the client for this project",
            "examples": [
              10000,
              25000
            ]
          },
          "client_accepted_taskrabbit_policy": {
            "type": "boolean",
            "nullable": true,
            "description": "Indicates whether the client accepted TaskRabbit's Terms of Service and Privacy Policy",
            "examples": [
              true,
              false
            ]
          },
          "agreement_external_reference": {
            "type": "string",
            "nullable": true,
            "description": "Partner provided transaction information for reconciliation and cross-referencing",
            "examples": [
              "partner-order-12345",
              "invoice-ref-abc123"
            ]
          },
          "agreement_accounting_reference": {
            "type": "string",
            "nullable": true,
            "description": "Partner provided accounting information for reconciliation and cross-referencing",
            "examples": [
              "partner-order-12345",
              "invoice-ref-abc123"
            ]
          }
        }
      },
      "AgreementPriceQuote": {
        "description": "This is the total price for the Project Agreement.",
        "type": "object",
        "properties": {
          "service_item_terms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceItemTermPriceQuote"
            }
          },
          "agreement_terms": {
            "$ref": "#/components/schemas/AgreementTerms"
          },
          "total_amount": {
            "description": "The total cost for this Project Agreement",
            "$ref": "#/components/schemas/Price"
          }
        }
      },
      "AgreementTerms": {
        "description": "Additional Agreement Contract Terms that apply to an entire agreement, across all of its constituent Service Item Terms.",
        "type": "object",
        "properties": {
          "agreement_minimum_price": {
            "description": "The minimum price total for this booked Agreement. If the Sum of the Service Item Terms' prices is less than this value, this value will be used instead for the total.",
            "$ref": "#/components/schemas/Price"
          }
        }
      },
      "ServiceItemTerm": {
        "description": "The individual services in a project.",
        "type": "object",
        "properties": {
          "service_uuid": {
            "$ref": "#/components/schemas/ServiceUuid"
          },
          "service_item_term_external_reference": {
            "type": "string",
            "description": "Partner supplied information related to a specific Service Item Term.",
            "examples": [
              "cart-line:12345"
            ]
          },
          "service_item_term_description": {
            "description": "Partner supplied product-specific description to be displayed in Task description.",
            "examples": [
              "Three-tier wooden rabbit hutch with plush cushions. Follow the instructions included in the packaging."
            ]
          },
          "product_name": {
            "description": "Partner supplied product name to be included in a Task description.",
            "type": "string",
            "examples": [
              "Bunny's Dream House - Birch"
            ]
          },
          "product_external_reference": {
            "description": "Partner supplied product identifier (SKU)",
            "examples": [
              "abc-0014"
            ]
          },
          "quantity": {
            "type": "integer",
            "description": "The quantity of this service item term",
            "minimum": 1,
            "default": 1,
            "examples": [
              1,
              2,
              5
            ]
          }
        }
      },
      "ServiceItemTermPriceQuote": {
        "description": "The price for individual services in a project.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ServiceItemTerm"
          },
          {
            "type": "object",
            "properties": {
              "total_amount": {
                "description": "The total cost for this individual Service Item Term",
                "$ref": "#/components/schemas/Price"
              }
            }
          }
        ]
      },
      "FullLocation": {
        "type": "object",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/FullAddress"
          }
        }
      },
      "FullAddress": {
        "description": "A complete mailing address at which the Services are to be completed.",
        "required": [
          "line_1",
          "line_2",
          "city",
          "region",
          "country",
          "postal_code"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/Address"
          }
        ]
      },
      "Address": {
        "description": "A complete mailing address at which the Services are to be completed. Note that in an Estimate context, postal code and country are required.",
        "type": "object",
        "properties": {
          "line_1": {
            "type": "string",
            "description": "Street Address Line 1",
            "examples": [
              "123 Main Street"
            ]
          },
          "line_2": {
            "type": "string",
            "description": "Street Address Line 2",
            "examples": [
              "Apt 123"
            ]
          },
          "city": {
            "type": "string",
            "description": "City",
            "examples": [
              "New York"
            ]
          },
          "region": {
            "type": "string",
            "description": "Region (e.g. State, Province, etc)",
            "examples": [
              "New York"
            ]
          },
          "country": {
            "type": "string",
            "description": "Country",
            "examples": [
              "USA"
            ]
          },
          "postal_code": {
            "type": "string",
            "description": "A postal code at which the Services are to be completed.",
            "examples": [
              "10019"
            ]
          }
        }
      },
      "Price": {
        "description": "The cost represented by a number of cents and a currency.",
        "type": "object",
        "properties": {
          "cents": {
            "type": "integer",
            "description": "The Positive Interger Price Value represented as the smallest whole unit of the currency. As an example, in currency USD, 1000 = $10.00",
            "examples": [
              1000
            ]
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          }
        }
      },
      "Currency": {
        "type": "string",
        "description": "The financial currency used for the transaction. NOTE As of version 1.0 only USD is available.",
        "enum": [
          "USD"
        ]
      },
      "ServiceUuid": {
        "type": "string",
        "format": "uuid",
        "description": "The unique identifier for a partner's Service."
      },
      "InvalidBookRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorResponse"
          },
          {
            "type": "object",
            "properties": {
              "error": {
                "properties": {
                  "message": {
                    "examples": [
                      "Invalid book request"
                    ]
                  },
                  "code": {
                    "examples": [
                      "invalid_book_request"
                    ]
                  }
                }
              }
            }
          }
        ]
      },
      "ValidationError": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorResponse"
          },
          {
            "type": "object",
            "properties": {
              "error": {
                "properties": {
                  "message": {
                    "examples": [
                      "client[email] is missing, client[email] is empty"
                    ]
                  },
                  "code": {
                    "examples": [
                      "validation_error"
                    ]
                  }
                }
              }
            }
          }
        ]
      }
    },
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://{{partnership_auth_token_url}}/oauth2/token",
            "scopes": {
              "partner_platform_api/booking": "Placeholder Scope"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "OAuth2": [
        "partner_platform_api/booking"
      ]
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 104,
      "1": 193,
      "2": 191,
      "3": 213,
      "4": 189,
      "5": 36,
      "6": 65,
      "7": 60,
      "8": 189,
      "9": 39,
      "10": 88,
      "11": 109
    }
  }
}
```