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

# Bid Project Agreement

Once the customer chooses their desired date/time window for their project, the Bid endpoint will create an agreement for that specific date/time window and return the most accurate pricing. It will also return the Project ID that is required to complete the booking.

# 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/bid": {
      "post": {
        "tags": [
          "Project Booking APIs"
        ],
        "summary": "Bid Project Agreement",
        "description": "Once the customer chooses their desired date/time window for their project, the Bid endpoint will create an agreement for that specific date/time window and return the most accurate pricing. It will also return the Project ID that is required to complete the booking.",
        "operationId": "projectBid",
        "requestBody": {
          "description": "Receive a formal Price Quote and Project ID for a given draft Project Agreement.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BidRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BidResponse"
                },
                "examples": {
                  "SingleServiceItemCompleteBid": {
                    "summary": "1 ServiceItemTerm with all optional fields",
                    "value": {
                      "status": 201,
                      "request_id": "550e8400-e29b-41d4-a716-446655440000",
                      "data": {
                        "project": {
                          "project_uuid": "6aa34486-b124-41ba-a411-69ee9438eb47",
                          "state": "DRAFT",
                          "locale": "en-US",
                          "currency": "USD",
                          "parties": {
                            "service_provider_tenant_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
                          },
                          "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": null
                        },
                        "invalid_after": "2024-10-10T14:15:45.083Z"
                      }
                    }
                  },
                  "SingleServiceItemMinimalBid": {
                    "summary": "1 ServiceItemTerm with no optional fields",
                    "value": {
                      "status": 201,
                      "request_id": "550e8400-e29b-41d4-a716-446655440000",
                      "data": {
                        "project": {
                          "project_uuid": "6aa34486-b124-41ba-a411-69ee9438eb47",
                          "state": "DRAFT",
                          "locale": "en-US",
                          "currency": "USD",
                          "parties": {
                            "service_provider_tenant_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
                          },
                          "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",
                                "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": null
                        },
                        "invalid_after": "2024-10-10T14:15:45.083Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid bid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvalidBidRequest"
                }
              }
            }
          }
        }
      }
    }
  },
  "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"
              }
            }
          }
        }
      },
      "BidRequest": {
        "description": "Information given to bid for a project agreement.",
        "type": "object",
        "required": [
          "locale",
          "currency",
          "location",
          "service_item_terms",
          "target_start_time"
        ],
        "properties": {
          "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"
          },
          "location": {
            "$ref": "#/components/schemas/FullLocation"
          },
          "service_item_terms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceItemTermRequest"
            }
          },
          "target_start_time": {
            "$ref": "#/components/schemas/TargetStartTime"
          }
        }
      },
      "BidResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SuccessResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "project": {
                    "$ref": "#/components/schemas/Project"
                  },
                  "invalid_after": {
                    "type": "string",
                    "format": "date-time",
                    "description": "The project agreement is no longer valid and cannot be booked after this date."
                  }
                }
              }
            }
          }
        ]
      },
      "TargetStartTime": {
        "type": "string",
        "description": "The earliest time a Tasker can begin a project.",
        "format": "date-time",
        "examples": [
          "2024-06-11T20:00:00.000Z"
        ]
      },
      "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"
          }
        }
      },
      "ServiceItemTermRequest": {
        "required": [
          "service_uuid"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/ServiceItemTerm"
          }
        ]
      },
      "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."
      },
      "InvalidBidRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorResponse"
          },
          {
            "type": "object",
            "properties": {
              "error": {
                "properties": {
                  "message": {
                    "examples": [
                      "Invalid bid request"
                    ]
                  },
                  "code": {
                    "examples": [
                      "invalid_bid_request"
                    ]
                  }
                }
              }
            }
          }
        ]
      }
    },
    "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
    }
  }
}
```