> ## Documentation Index > Fetch the complete documentation index at: https://help.gorelo.io/llms.txt > Use this file to discover all available pages before exploring further. # Lists billing contracts, each with the service lines it is made of. > A contract is the agreement with a client; a service line is one set of labour terms and products inside it. Most contracts have a single service line. A service line's id is the same identifier a time entry's `ServiceLineId` carries, so a contract's service lines are what a time entry can be billed against. Service lines ride inside the contract rather than being fetched per contract, so a page of contracts costs a fixed number of queries. Every filter is optional; the client filter is a comma-separated list and a contract matches if its client is any of them. A well-formed value that matches nothing - a client id that owns no contracts - is an empty page, not a 404. Timestamps are UTC; `StartDate` and `EndDate` are stored as dates, so they are always midnight. `Status` is derived, because a contract has no stored status: 3 `Archived` when the contract has been archived, 2 `Expired` when its end date is behind the service provider's own today, and 1 `Active` otherwise. Deleted contracts are not listed at all. Archived contracts are left out unless `statusIds` names Archived; expired ones are listed by default, so a caller that wants only live contracts passes `statusIds=1`. `RecurringAmount` and `RecurringCost` cover the products billed on the contract's own recurring schedule, excluding one-off lines. Amount is before tax; cost is the unit cost recorded against each product line multiplied by its quantity, so the difference between them is the periodic margin. A contract's two figures are exactly the sum of its service lines'. `LaborTerms` says how a service line bills time - Unlimited Hours, Hourly, Block Hours, No Labor Terms, or Limited Hours - and `LaborRates` says how an hour is priced for the two that bill hourly, and is null for the rest. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/contracts openapi: 3.0.4 info: title: Public API description: Gorelo Public API documentation. version: 1.0.0 servers: - url: https://api.usw.gorelo.io description: US - url: https://api.aue.gorelo.io description: Australia security: - ApiKeyAuth: [] tags: - name: Attachments description: "Uploading a file, for anything that can carry one. One endpoint rather than one per record\r\ntype, because the upload itself is identical - only the record it is checked against differs." - name: Alerts description: Alerts management operations - name: Assets description: Assets management operations - name: Billing description: Billing management operations - name: Tickets description: Tickets management operations - name: Clients description: Clients management operations - name: Contacts description: Contacts management operations - name: Deletions description: Deletions management operations - name: Documents description: Documents management operations - name: Forms description: Forms management operations - name: Organization description: Organization management operations - name: Projects description: Projects management operations paths: /v1/contracts: get: tags: - Billing summary: Lists billing contracts, each with the service lines it is made of. description: "A contract is the agreement with a client; a service line is one set of labour terms and\r\nproducts inside it. Most contracts have a single service line. A service line's id is the\r\nsame identifier a time entry's `ServiceLineId` carries, so a contract's service lines\r\nare what a time entry can be billed against.\r\n\n\r\nService lines ride inside the contract rather than being fetched per contract, so a page of\r\ncontracts costs a fixed number of queries. Every filter is optional; the client filter is a\r\ncomma-separated list and a contract matches if its client is any of them. A well-formed value\r\nthat matches nothing - a client id that owns no contracts - is an empty page, not a 404.\r\nTimestamps are UTC; `StartDate` and `EndDate` are stored as dates, so they are\r\nalways midnight.\r\n\n`Status` is derived, because a contract has no stored status: 3 `Archived` when\r\nthe contract has been archived, 2 `Expired` when its end date is behind the service\r\nprovider's own today, and 1 `Active` otherwise. Deleted contracts are not listed at\r\nall. Archived contracts are left out unless `statusIds` names Archived; expired ones\r\nare listed by default, so a caller that wants only live contracts passes\r\n`statusIds=1`.\r\n\n`RecurringAmount` and `RecurringCost` cover the products billed on the contract's\r\nown recurring schedule, excluding one-off lines. Amount is before tax; cost is the unit cost\r\nrecorded against each product line multiplied by its quantity, so the difference between\r\nthem is the periodic margin. A contract's two figures are exactly the sum of its service\r\nlines'.\r\n\n`LaborTerms` says how a service line bills time - Unlimited Hours, Hourly, Block Hours,\r\nNo Labor Terms, or Limited Hours - and `LaborRates` says how an hour is priced for the\r\ntwo that bill hourly, and is null for the rest.\r\n" operationId: get_v1_contracts parameters: - name: Cursor in: query description: >- Opaque pagination cursor from a previous page; omit for the first page. Only valid against the same filters that produced it. schema: type: string - name: PageSize in: query description: >- Number of items per page, 1-200 (default 50). Out of range is rejected, not clamped. schema: type: integer format: int32 default: 50 - name: ClientIds in: query description: >- Comma-separated client ids; keeps only contracts billed to any of them. schema: type: string - name: StatusIds in: query description: >- Comma-separated status ids: 1 Active, 2 Expired, 3 Archived. Omitted returns Active and Expired (archived excluded). Any other id is a 400. schema: type: string responses: '200': description: OK content: text/plain: schema: $ref: '#/components/schemas/ContractModelListBaseResponse' application/json: schema: $ref: '#/components/schemas/ContractModelListBaseResponse' text/json: schema: $ref: '#/components/schemas/ContractModelListBaseResponse' '400': description: Bad Request content: text/plain: schema: $ref: '#/components/schemas/ObjectBaseResponse' application/json: schema: $ref: '#/components/schemas/ObjectBaseResponse' text/json: schema: $ref: '#/components/schemas/ObjectBaseResponse' '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/ObjectBaseResponse' application/json: schema: $ref: '#/components/schemas/ObjectBaseResponse' text/json: schema: $ref: '#/components/schemas/ObjectBaseResponse' '500': description: Internal Server Error content: text/plain: schema: $ref: '#/components/schemas/ObjectBaseResponse' application/json: schema: $ref: '#/components/schemas/ObjectBaseResponse' text/json: schema: $ref: '#/components/schemas/ObjectBaseResponse' components: schemas: ContractModelListBaseResponse: type: object properties: StatusCode: $ref: '#/components/schemas/HttpStatusCode' IsSuccess: type: boolean Data: type: array items: $ref: '#/components/schemas/ContractModel' nullable: true DataContext: $ref: '#/components/schemas/PaginationDataContext' Notifications: type: array items: $ref: '#/components/schemas/Error' additionalProperties: false ObjectBaseResponse: type: object properties: StatusCode: $ref: '#/components/schemas/HttpStatusCode' IsSuccess: type: boolean Data: nullable: true DataContext: $ref: '#/components/schemas/ErrorDataContext' Notifications: type: array items: $ref: '#/components/schemas/Error' additionalProperties: false HttpStatusCode: enum: - 100 - 101 - 102 - 103 - 200 - 201 - 202 - 203 - 204 - 205 - 206 - 207 - 208 - 226 - 300 - 301 - 302 - 303 - 304 - 305 - 306 - 307 - 308 - 400 - 401 - 402 - 403 - 404 - 405 - 406 - 407 - 408 - 409 - 410 - 411 - 412 - 413 - 414 - 415 - 416 - 417 - 421 - 422 - 423 - 424 - 426 - 428 - 429 - 431 - 451 - 500 - 501 - 502 - 503 - 504 - 505 - 506 - 507 - 508 - 510 - 511 type: integer format: int32 ContractModel: type: object properties: Id: type: integer description: Identifier of the contract. format: int64 example: 4021 Name: type: string description: Name of the contract. example: All Labor Terms Example Status: $ref: '#/components/schemas/CodeModel' ClientId: type: integer description: Client the contract is billed to. format: int64 example: 88 LocationIds: type: array items: type: integer format: int64 description: "The client locations the contract is scoped to, as location ids ascending. An empty array\r\nwhen the contract covers all of the client's locations (see\r\n`IsForAllLocations`); also empty when a location-scoped contract's locations\r\nhave all been removed. Never null." IsForAllLocations: type: boolean description: "Whether the contract covers every one of the client's locations rather than the specific\r\nones named in `LocationIds`. When true, `LocationIds` is empty by\r\ndefinition." CreatedOn: type: string description: When the contract was created, in UTC. format: date-time nullable: true UpdatedOn: type: string description: >- When the contract was last changed, in UTC. Null when it has never been changed. format: date-time nullable: true Reference: type: string description: "The contract's invoice reference, free text. Null when it is not set.\r\n\n\r\nThis is the product's invoice-reference field, and it doubles as a template: values such as\r\n`{{contractgroupname}}-{{billingmonth}}` are common and are substituted when an invoice\r\nis raised. It is returned exactly as stored, tokens included.\r\n" nullable: true example: MSA-2025-014 StartDate: type: string description: Date the contract's coverage starts, a calendar date. format: date EndDate: type: string description: >- Date the contract's coverage ends, a calendar date, or null when it is open-ended. format: date nullable: true RepeatPeriod: $ref: '#/components/schemas/CodeModel' RecurringAmount: type: number description: "Total recurring amount the contract bills each period, before tax, summed across its service\r\nlines. Zero when the contract has no recurring products." format: double example: 3870 RecurringCost: type: number description: "Total recurring cost of the contract's recurring products each period, summed across its\r\nservice lines. Cost is the unit cost recorded against each product line multiplied by its\r\nquantity, so RecurringAmount minus RecurringCost is the contract's periodic margin." format: double example: 1681.36 ServiceLines: type: array items: $ref: '#/components/schemas/ContractServiceLineModel' description: "The contract's service lines. An empty array when the contract has none; never null.\r\nSoft-deleted service lines are omitted." additionalProperties: false description: A billing contract and the service lines it is made of. PaginationDataContext: type: object properties: Pagination: $ref: '#/components/schemas/PaginatedResponse' additionalProperties: false description: "The `DataContext` of a cursor-paginated success response: carries the paging metadata\r\nfor the returned page." Error: type: object properties: Code: pattern: ^[0-9]{6}$ type: string description: 6-digit MMTTNN error code. See the Public API error-code registry. example: '070101' Message: type: string PropertyName: type: string nullable: true ActionHint: type: string nullable: true DocUrl: type: string nullable: true additionalProperties: false ErrorDataContext: type: object properties: TraceId: type: string description: Request correlation id. Quote this when reporting a problem. nullable: true additionalProperties: false description: "The `DataContext` of an error response: carries the correlation id for the failed\r\nrequest." CodeModel: type: object properties: Id: type: integer description: >- Numeric identifier of the coded value (e.g. status, priority, type, or source id). format: int64 example: 1 Name: type: string description: Display name of the coded value. additionalProperties: false description: >- A coded value, such as a status, priority, type or source, as an id and a display name. ContractServiceLineModel: type: object properties: Id: type: integer description: Identifier of the service line. format: int64 example: 88214 Name: type: string description: Name of the service line. example: Managed Services CreatedOn: type: string description: When the service line was created, in UTC. format: date-time nullable: true UpdatedOn: type: string description: >- When the service line was last changed, in UTC. Null when it has never been changed. format: date-time nullable: true LaborTerms: $ref: '#/components/schemas/CodeModel' LaborRates: $ref: '#/components/schemas/CodeModel' RecurringAmount: type: number description: Recurring amount this service line bills each period, before tax. format: double example: 2280 RecurringCost: type: number description: >- Recurring cost of this service line's recurring products each period. format: double example: 591.36 additionalProperties: false description: "One service line inside a contract: a Billing.Agreement row. Its Id is the value a time entry's\r\nServiceLineId carries." PaginatedResponse: type: object properties: NextCursor: type: string nullable: true PreviousCursor: type: string nullable: true HasMore: type: boolean HasPrevious: type: boolean TotalCount: type: integer format: int32 additionalProperties: false securitySchemes: ApiKeyAuth: type: apiKey description: >- Your Gorelo API key. See [Generate API key](/generate-api-key). If your data is hosted in Australia, click the base URL at the top of this page and select `https://api.aue.gorelo.io`. name: X-API-Key in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.