API Documentation

API Endpoint

Contracts

Contracts

For more details on contracts please refer to the help article.

The contract object represents recurring financial commitments such as recurring budgets. Recurring commitments are either created automatically or triggered manually.

Please note that we rate limit POST requests for generating recurring budgets to 50 requests per minute.

Supported attributes

  • interval_id (integer)

  • next_occurrence_on (date)

  • ends_on (date)

  • template_id (integer)

  • copy_purchase_order_number (boolean)

  • copy_expenses (boolean)

The following interval_id values are available:

  • 1 (monthly)

  • 2 (bi-weekly)

  • 3 (weekly)

  • 4 (annual)

  • 5 (semiannual)

  • 6 (quarterly)

The following attributes are mandatory:

  • interval_id

  • template_id

  • next_occurrence_on (on create only)

In addition, next_occurrence_on date must be after today and after template’s date. Also, ends_on date has to be on or after next_occurrence_on if set.

Note that template_id has to point to a valid financial object, such as a budget that is to be recurred.

Supported filter params

  • id (integer)

  • contract_interval_id (integer)

  • starts_on (date)

  • ends_on (date)

  • next_occurrence_on (date)

Filter operations are supported on this endpoint.

Supported sort params

No sorting is supported on this endpoint. Default sorting is by id, ascending.

GET /api/v2/contracts
Requestsreturns contracts

GET  /api/v2/contracts

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "1",
      "type": "contracts",
      "attributes": {
        "ends_on": null,
        "starts_on": "2025-08-03",
        "next_occurrence_on": "2025-09-01",
        "interval_id": 1,
        "copy_purchase_order_number": false,
        "copy_expenses": false,
        "use_rollover_hours": false
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "244"
          }
        },
        "template": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "2",
      "type": "contracts",
      "attributes": {
        "ends_on": null,
        "starts_on": "2025-08-03",
        "next_occurrence_on": "2025-09-01",
        "interval_id": 1,
        "copy_purchase_order_number": false,
        "copy_expenses": false,
        "use_rollover_hours": false
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "244"
          }
        },
        "template": {
          "meta": {
            "included": false
          }
        }
      }
    },
    {
      "id": "3",
      "type": "contracts",
      "attributes": {
        "ends_on": null,
        "starts_on": "2025-08-03",
        "next_occurrence_on": "2025-09-01",
        "interval_id": 1,
        "copy_purchase_order_number": false,
        "copy_expenses": false,
        "use_rollover_hours": false
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "244"
          }
        },
        "template": {
          "meta": {
            "included": false
          }
        }
      }
    }
  ],
  "links": {
    "first": "http://api-test.productive.io/api/v2/contracts?page%5Bnumber%5D=1&page%5Bsize%5D=30",
    "last": "http://api-test.productive.io/api/v2/contracts?page%5Bnumber%5D=1&page%5Bsize%5D=30"
  },
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 3,
    "page_size": 30,
    "max_page_size": 200
  }
}

Get contracts
GET/api/v2/contracts

GET /api/v2/contracts/1
Requestsreturns contract

GET  /api/v2/contracts/4

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "4",
    "type": "contracts",
    "attributes": {
      "ends_on": null,
      "starts_on": "2025-08-03",
      "next_occurrence_on": "2025-09-01",
      "interval_id": 1,
      "copy_purchase_order_number": false,
      "copy_expenses": false,
      "use_rollover_hours": false
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "245"
        }
      },
      "template": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "meta": {}
}

Gets a contract
GET/api/v2/contracts/{id}

URI Parameters
HideShow
id
number (required) Example: 1

contract id

template_id
number (required) Example: 1

template id

POST /api/v2/contracts
Requestscreates contract and starts recurringreturns error

POST  /api/v2/contracts

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "contracts",
    "attributes": {
      "interval_id": 1,
      "next_occurrence_on": "Sep  1, 2025"
    },
    "relationships": {
      "template": {
        "data": {
          "type": "deals",
          "id": "128"
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "6",
    "type": "contracts",
    "attributes": {
      "ends_on": null,
      "starts_on": "2025-08-01",
      "next_occurrence_on": "2025-09-01",
      "interval_id": 1,
      "copy_purchase_order_number": false,
      "copy_expenses": false,
      "use_rollover_hours": false
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "246"
        }
      },
      "template": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "meta": {}
}

POST  /api/v2/contracts

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "contracts",
    "attributes": {
      "interval_id": 1,
      "next_occurrence_on": "2025-09-01"
    },
    "relationships": {
      "template": {
        "data": {
          "type": "deals",
          "id": "0"
        }
      }
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "attribute is invalid",
      "source": {
        "pointer": "data/attributes/template"
      }
    }
  ]
}

Create a contract
POST/api/v2/contracts

PATCH /api/v2/contracts/1
Requestsupdates contractreturns errorreturns errorreturns errorreturns error

PATCH  /api/v2/contracts/10

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "contracts",
    "attributes": {
      "ends_on": "Sep 30, 2025"
    },
    "relationships": {
      "template": {
        "data": {
          "type": "deals",
          "id": "134"
        }
      }
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "10",
    "type": "contracts",
    "attributes": {
      "ends_on": "2025-09-30",
      "starts_on": "2025-08-03",
      "next_occurrence_on": "2025-09-01",
      "interval_id": 1,
      "copy_purchase_order_number": false,
      "copy_expenses": false,
      "use_rollover_hours": false
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "250"
        }
      },
      "template": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "meta": {}
}

PATCH  /api/v2/contracts/11

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "contracts",
    "attributes": {
      "next_occurrence_on": "Jul 29, 2025"
    },
    "relationships": {
      "template": {
        "data": {
          "type": "deals",
          "id": "136"
        }
      }
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "must be after today",
      "source": {
        "pointer": "data/attributes/next_occurrence_on"
      }
    },
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "must be after budget date",
      "source": {
        "pointer": "data/attributes/next_occurrence_on"
      }
    }
  ]
}

PATCH  /api/v2/contracts/12

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "contracts",
    "attributes": {
      "next_occurrence_on": "Aug  3, 2025"
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "must be after budget date",
      "source": {
        "pointer": "data/attributes/next_occurrence_on"
      }
    }
  ]
}

PATCH  /api/v2/contracts/13

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "contracts",
    "attributes": {
      "next_occurrence_on": "Aug  3, 2025"
    },
    "relationships": {
      "template": {
        "data": {
          "type": "deals",
          "id": "139"
        }
      }
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "must be after budget date",
      "source": {
        "pointer": "data/attributes/next_occurrence_on"
      }
    }
  ]
}

PATCH  /api/v2/contracts/15

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "contracts",
    "relationships": {
      "template": {
        "data": {
          "type": "deals",
          "id": "142"
        }
      }
    }
  }
}
Responses422
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "status": "422",
      "code": "invalid_attribute",
      "title": "Invalid Attribute",
      "detail": "must be after budget date",
      "source": {
        "pointer": "data/attributes/next_occurrence_on"
      }
    }
  ]
}

Update a contract
PATCH/api/v2/contracts/{id}

URI Parameters
HideShow
id
number (required) Example: 1

contract id

template_id
number (required) Example: 1

template id

DELETE /api/v2/contracts/1
Requestsdeletes contract

DELETE  /api/v2/contracts/16

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses204
This response has no content.

Deletes a contract
DELETE/api/v2/contracts/{id}

URI Parameters
HideShow
id
number (required) Example: 1

contract id

template_id
number (required) Example: 1

template id

POST /api/v2/contracts/1/generate
Requestsrestarts the budget interval

POST  /api/v2/contracts/19/generate

Headers
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "19",
    "type": "contracts",
    "attributes": {
      "ends_on": null,
      "starts_on": "2025-08-03",
      "next_occurrence_on": "2022-03-01",
      "interval_id": 1,
      "copy_purchase_order_number": false,
      "copy_expenses": false,
      "use_rollover_hours": false
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "257"
        }
      },
      "template": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "meta": {}
}

Generates new budget
POST/api/v2/contracts/{id}/generate

URI Parameters
HideShow
id
number (required) Example: 1

contract id

template_id
number (required) Example: 1

template id

Generated by aglio on 01 Aug 2025