# Agency

For TrustPager agencies: read your clients and their health, your clients' service requests and your commission, with an API key made on your agency's own workspace (agency:read). Read only, and never a client's own business data.

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### POST /agency/service-requests/:request_id/notes

Add a note to one of your agency's client service requests (an id from list_agency_service_requests). The client sees it on their request. Anyone on the agency's staff can, account managers included, while your agency still looks after that client. A note never reopens a finished request and never changes its status or queue.

**Scopes:** `service-requests:write` — [full detail](./agency/post-agency-service-requests-request-id-notes.md)

### GET /agency

Your agency's name, commission rate, signup link and how many clients and templates it has. Needs an API key made on the agency's own workspace.

**Scopes:** `agency:read` — [full detail](./agency/get-agency.md)

### GET /agency/clients/:client_id

One of your agency's clients, with the same health columns as list_agency_clients. client_id is the client's workspace id.

**Scopes:** `agency:read` — [full detail](./agency/get-agency-clients-client-id.md)

### GET /agency/commission

Your agency's commission: this month's estimate so far and the last 24 monthly statements with their lines. Never includes bank details. The owner sees the agency's figures (scope 'agency'); an account manager sees only the clients they brought in (scope 'mine'); systems architects are refused.

**Scopes:** `agency:read` — [full detail](./agency/get-agency-commission.md)

### GET /agency/team-commission

What your agency pays its own salespeople. For each person: their commission plan (one_off_percent on setup fees and services; first_months_percent on the client's first first_months paid months of subscription, then ongoing_percent, for ongoing_months more months or forever when null), this month so far, and the last 24 months of payouts with each client payment, its rate and the commission. Payout status: owed, paid, nothing_owed, or carried_forward (refunds took it below $0, so it comes off next month). Finished months are worked out when you ask. The owner sees the whole team; anyone else sees only themselves. TrustPager never pays salespeople: the agency pays them and marks the month paid.

**Scopes:** `agency:read` — [full detail](./agency/get-agency-team-commission.md)

### GET /agency/clients

Every client workspace (and template) your agency looks after, with its health: plan, what it pays us, trial end, users, website, last activity, open service requests and unfinished setup. Never returns the client's own business data. 100 a page.

**Scopes:** `agency:read` — [full detail](./agency/get-agency-clients.md)

### GET /agency/service-requests

Service requests from your agency's clients. queue 'agency' is waiting on your agency; 'platform' has been passed to TrustPager. Filter by status or client.

**Scopes:** `agency:read` — [full detail](./agency/get-agency-service-requests.md)

### GET /agency/websites

Your clients' websites: the GitHub repo and branch each is built from, and its latest syncs with their status (queued, copying, building, ready, published, failed), preview address and, for a failed build, the end of the build log.

**Scopes:** `agency:read` — [full detail](./agency/get-agency-websites.md)

### PATCH /agency/service-requests/:request_id/notes/:note_id

Change the text of a note you wrote on one of your agency's client service requests. Only your own notes, and only while your agency still looks after that client.

**Scopes:** `service-requests:write` — [full detail](./agency/patch-agency-service-requests-request-id-notes-note-id.md)

### PATCH /agency/team-commission/plans/:user_id

Agency owner only: set or change one salesperson's commission plan. Rates are percentages (10 = 10%, up to 100). Anything left out keeps its current value. Example, 100% of the first month then 10% of everything: one_off_percent 10, first_months 1, first_months_percent 100, ongoing_percent 10, ongoing_forever true. Every finished month is locked in at the old plan first, so a change applies from this month on; a person's first plan also covers the months since they joined.

**Scopes:** `agency:write` — [full detail](./agency/patch-agency-team-commission-plans-user-id.md)

### PATCH /agency/team-commission/payouts/:payout_id

Agency owner only: mark a salesperson's month paid once the agency has paid them (paid true, with an optional payment_reference such as the bank transfer reference), or undo that (paid false). Only a month with money owed can be marked paid.

**Scopes:** `agency:write` — [full detail](./agency/patch-agency-team-commission-payouts-payout-id.md)