ProofHub User Management API Guide

Auth method: API Key (Bearer Token)

Setup steps

1. Log in to ProofHub as an Administrator.
2. Navigate to Account Settings → API.
3. Generate a personal API token.
4. Include the token in all requests as an HTTP header: 'Authorization: Bearer {api_token}'.
5. Also set 'Content-Type: application/json' and 'User-Agent: {YourAppName}' headers.

List all people (users)

• Method: GET
• URL: https://{account}.proofhub.com/api/v3/people
• Watch out for: Returns all account members. Paginate using ?page= for accounts with many users.

Request example

GET /api/v3/people
Authorization: Bearer {api_token}
User-Agent: MyApp

Response example

[
  {
    "id": 101,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "role": "admin",
    "created_at": "2024-01-10T08:00:00Z"
  }
]

Get a single person

• Method: GET
• URL: https://{account}.proofhub.com/api/v3/people/{person_id}
• Watch out for: Returns 404 if the person_id does not exist or belongs to a different account.

Request example

GET /api/v3/people/101
Authorization: Bearer {api_token}
User-Agent: MyApp

Response example

{
  "id": 101,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "admin"
}

Invite a person (create user)

• Method: POST
• URL: https://{account}.proofhub.com/api/v3/people
• Watch out for: An invitation email is sent automatically. Duplicate email addresses return a 422 error.

Request example

POST /api/v3/people
Authorization: Bearer {api_token}
Content-Type: application/json

{"name":"John Smith","email":"john@example.com","role":"member"}

Response example

{
  "id": 202,
  "name": "John Smith",
  "email": "john@example.com",
  "role": "member",
  "created_at": "2025-06-01T10:00:00Z"
}

Update a person

• Method: PUT
• URL: https://{account}.proofhub.com/api/v3/people/{person_id}
• Watch out for: Full PUT semantics; omitted optional fields may be cleared. Verify field behavior before bulk updates.

Request example

PUT /api/v3/people/202
Authorization: Bearer {api_token}
Content-Type: application/json

{"name":"John A. Smith","phone":"+1-555-0100"}

Response example

{
  "id": 202,
  "name": "John A. Smith",
  "phone": "+1-555-0100"
}

Remove a person

• Method: DELETE
• URL: https://{account}.proofhub.com/api/v3/people/{person_id}
• Watch out for: Deletion is permanent and removes the user from all projects. Cannot be undone via API.

Request example

DELETE /api/v3/people/202
Authorization: Bearer {api_token}
User-Agent: MyApp

Response example

HTTP 204 No Content

List project members

• Method: GET
• URL: https://{account}.proofhub.com/api/v3/projects/{project_id}/people
• Watch out for: Project-level roles differ from account-level roles. Check both contexts when auditing permissions.

Request example

GET /api/v3/projects/55/people
Authorization: Bearer {api_token}
User-Agent: MyApp

Response example

[
  {"id": 101, "name": "Jane Doe", "role": "manager"},
  {"id": 202, "name": "John Smith", "role": "member"}
]

Add person to project

• Method: POST
• URL: https://{account}.proofhub.com/api/v3/projects/{project_id}/people
• Watch out for: User must already exist as an account member before being added to a project.

Request example

POST /api/v3/projects/55/people
Authorization: Bearer {api_token}
Content-Type: application/json

{"person_id": 202}

Response example

{
  "id": 202,
  "name": "John Smith",
  "role": "member"
}

Remove person from project

• Method: DELETE
• URL: https://{account}.proofhub.com/api/v3/projects/{project_id}/people/{person_id}
• Watch out for: Removes project access only; does not delete the account-level user record.

Request example

DELETE /api/v3/projects/55/people/202
Authorization: Bearer {api_token}
User-Agent: MyApp

Response example

HTTP 204 No Content

• Rate limits: ProofHub enforces a rate limit of 30 requests per 10 seconds per API token.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: When the limit is exceeded, the API returns HTTP 429. The response includes rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). Retry after the reset timestamp.
• Pagination method: offset
• Default page size: 25
• Max page size: 100
• Pagination pointer: page

• Webhooks available: No
• Webhook notes: ProofHub does not document a native outbound webhook system in its official API documentation as of the research date.
• Alternative event strategy: Poll the /people endpoint periodically to detect user additions, updates, or removals.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Ultimate Control
• Endpoint: Not documented

Limitations:

• No SCIM 2.0 endpoint is documented or available in ProofHub's official API or help documentation.
• SSO via Okta is supported but automated SCIM provisioning/deprovisioning is not natively available.
• Ultimate Control plan is required for SSO; SCIM support status remains undocumented.

Three core automation scenarios are supported by the API. Onboarding: POST /people to create the account record and trigger the invite email, then POST /projects/{project_id}/people for each project assignment using the returned id.

Offboarding: GET /people to resolve the user's id by email, optionally enumerate project memberships via /projects/{project_id}/people for an audit trail, then DELETE /people/{person_id} - this call is permanent and cannot be undone via API, so person_id must be verified before execution.

Directory sync: paginate GET /people? page=N to retrieve the full user list, diff against the external source by email, and apply POST/PUT/DELETE as needed.

Because there are no webhooks, sync jobs must be scheduled; large accounts will issue many paginated requests, increasing exposure to the 30-requests-per-10-seconds rate limit. Implement exponential backoff on HTTP 429 and respect the X-RateLimit-Reset header.

Onboard a new employee

1. POST /api/v3/people with name, email, and role to create the account-level user (invitation email sent automatically).
2. Retrieve the new user's id from the POST response.
3. POST /api/v3/projects/{project_id}/people with the new person_id for each project they should join.

Watch out for: The invited user must accept the email invitation before they can actively use ProofHub, but the API record is created immediately.

Offboard a departing employee

1. GET /api/v3/people to locate the user's id by email.
2. GET /api/v3/projects to enumerate all projects, then GET /api/v3/projects/{project_id}/people to confirm project memberships (optional audit step).
3. DELETE /api/v3/people/{person_id} to permanently remove the user from the account and all projects.

Watch out for: Deletion is irreversible via API. Verify the correct person_id before issuing the DELETE request.

Sync account users to an external directory

1. GET /api/v3/people?page=1 and paginate through all pages (default 25 per page) to retrieve the full user list.
2. Compare returned records against the external directory by email field.
3. POST new users, PUT changed fields for existing users, and DELETE removed users as needed.
4. Implement exponential backoff when HTTP 429 is received, respecting X-RateLimit-Reset.

Watch out for: No webhook support means sync must be scheduled (e.g., hourly polling). Large accounts may require many paginated requests, increasing rate-limit exposure.

Several non-obvious constraints affect production integrations. The API token is bound to the generating user - if that user is removed, every downstream call using their token fails silently from the perspective of dependent systems; token ownership should be assigned to a dedicated service account.

PUT /people/{id} uses full-replacement semantics for at least some fields, meaning a partial update payload can clear data; test against a non-critical record before running bulk updates. Inviting a user via POST /people dispatches the invitation email immediately with no dry-run or suppression option, which matters in staging environments.

The User-Agent header is required on every request; omitting it may result in rejected calls. No official SDK is published, so all integrations require raw HTTP.

For teams building a unified identity graph across their SaaS stack, the absence of SCIM and webhooks means ProofHub user state must be inferred from periodic API snapshots rather than event-driven signals - a meaningful architectural gap when ProofHub is one node in a broader identity graph that includes HR systems, IdPs, and other SaaS tools.