Contracts

These endpoints need the Sales area of the key's role, as contracts do in ITFlow: Read to list them, Modify to change them, and Full to delete one or a block of hours. See Keys and permissions.

Read

contract_status is Draft, Active, Ended or Cancelled. With contract_id, hours is its prepaid hours - bought, used, left, lapsed, next_expiry and each of its blocks - and signature its latest signing request: its contract_signature_id, state - sent or viewed while it waits on the client, countersign once they signed, signed by both, or withdrawn - and who it went to.

Fields: contract_id, contract_name, contract_status, contract_type, contract_details, contract_client_id, contract_rate_standard, contract_rate_after_hours, contract_net_terms, contract_support_hours, contract_start_date, contract_end_date, contract_created_at, contract_updated_at, contract_archived_at, contract_term_months, contract_auto_renew, contract_notice_days, contract_sla_low_id, contract_sla_medium_id, contract_sla_high_id, contract_sla_urgent_id, contract_template_id, contract_contact_id, contract_owner_id, contract_notes, contract_renewed_at, contract_reminded_at, contract_cancelled_at, contract_cancel_reason, contract_created_by, contract_monthly_hours, contract_hours_alert, contract_hours_alerted_at, contract_recurring_invoice_id, contract_recurring_stopped_at.

Create and update

Update takes contract_id and changes only what you send. A contract stays with its client and in its status - those change through the calls below. One out for signature whose wording changes has that request withdrawn; the answer's withdrawn is 1 then.

Activate, renew, cancel and delete

Each takes contract_id and client_id.

• Activate takes start_date, the day a draft is in force from.
• Renew takes end_date, its new last day - after its current one, and not in the past.
• Cancel takes last_day, the day it's in force until, and a reason. A signing request still out is withdrawn.
• Delete needs Full. Not once tickets drew on its prepaid hours, or it was signed by both sides.

Activate, renew and cancel start or stop its recurring invoice to match - the answer's recurring says which.

Signing

Send takes contract_id, client_id, and contact_id - one of the client's contacts with an email address - or to_name and to_email, with a note for the email. They get a link to read and sign it. With contract_signature_id, the link of a request still waiting goes again instead. The answer has contract_signature_id, and emailed - 0 when ITFlow doesn't send mail, and the link is then on the contract's page to send yourself.

Withdraw takes contract_id, client_id and contract_signature_id, and the link no longer signs anything.

Countersigning is done in ITFlow.

Prepaid hours

Add hours (contract_hours/create.php) takes contract_id, client_id, hours and bought (the day they were bought), both required, and expires, price, note, and invoice - 1 makes a draft invoice for them, in the income category you name. They go on a draft or active contract, or a cancelled one until its last day. The answer has invoice_id and invoice_reference when an invoice was made.

Delete hours (contract_hours/delete.php) takes contract_block_id - from the contract's hours - and client_id. Time drawn from them keeps them; an invoice made for them stays.

Draw (contracts/draw.php) takes contract_id and client_id, and draws the time on the client's done tickets waiting to bill from its prepaid hours now - or just ticket_id's. The nightly run does it too. The answer has tickets, hours, what's left, and overage - hours over what was left, still to bill.

Put back (contracts/put_back.php) takes contract_id, client_id and ticket_id, and the ticket's time is to bill as usual again - not once it's on an invoice. The answer has hours.

The recurring invoice

Recurring (contracts/recurring.php) takes contract_id, client_id, and recurring_invoice_id - one of the client's that isn't another contract's - to link, or the fields of a new one to make: item_name and amount, both required, and frequency (month, the default, quarter or year), start (its first invoice), description, tax_id, category and auto_send. It runs while the contract is in force. The answer has recurring_invoice_id, reference and state.

Unlink (contracts/unlink.php) takes contract_id and client_id. The recurring invoice carries on as it is, running or paused.