Team, settings and profile

This page gathers the tools that run the organization: team members and their invitations, the company details printed on quotations, and your own profile. Most are for the owner and admin roles, some for the owner alone, and each tool says who may use it.

Six roles can be assigned: admin, sales, purchasing, technical, viewer and viewer_no_pricing. The admin manages the team and integrations, while billing, the organization's own record and the team activity log stay with the owner. Sales and purchasing work on bids, quotations and the catalog, and both see sale prices. Sales does not see cost prices or supplier quotes, while purchasing sees both sides. Technical reads the catalog, manufacturers and tenders with no prices at all. Viewer is read-only with all prices, and viewer (no pricing) is read-only without prices. The owner is whoever created the organization: that role cannot be assigned, changed or removed with these tools.

Team members and invitations

An invitation lasts 7 days. Seats are counted from current members and pending invitations together.

team_list

Lists the organization's members, each with their email and mobile number, and the pending invitations that can still be accepted. It is where the membership and invitation IDs for the other team tools come from.

Read-only · scope team.read · roles: owner, admin · Pro and Enterprise plans

No parameters.

Returns: members (each with id, the membership ID, user_id, role, created_at and a profiles object holding email, first_name, last_name, full_name, phone_number and company_name) and invitations (each with id, email, phone_number, role, status and expires_at).

• Expired, accepted and cancelled invitations are not listed: only those that can still be accepted appear.

team_update_role

Changes a team member's role. The owner's role can never be changed, and owner can never be assigned with this tool.

Changes data · scope team.write · roles: owner, admin · Pro and Enterprise plans

{
  "member_id": 27,
  "role": "purchasing"
}

Returns: A confirmation, success: true.

• Only the owner is protected: changing the owner's role answers 403, while any other member's role, an admin's included, can be changed. An unknown member answers 404.
• The new role applies to the member's next requests at once.

team_remove

Removes a member from the organization and ends their access to the platform. This cannot be undone: to bring them back you invite them again. The owner cannot be removed.

Deletes or overwrites data · scope team.write · roles: owner, admin · Pro and Enterprise plans

Returns: A confirmation, success: true.

• Trying to remove the owner answers 403, and an unknown member answers 404.
• API keys the member created stop working once they leave the organization.

team_invite_create

Emails an invitation to join the organization with a chosen role. The invitee's mobile (WhatsApp) number is required beside their email; it is copied to their profile when they accept, and the platform recognizes them by it, for example when approving WhatsApp group join requests. Members and pending invitations count together against your plan's seat limit, or against the paid seats when your subscription is billed per user. At the limit the owner adds a seat from the billing or team page in the app, because that charges the card.

Changes data · scope team.write · roles: owner, admin · Pro and Enterprise plans

{
  "email": "layla.hassan@acme-medical.example",
  "phone_number": "+966501234567",
  "role": "sales"
}

Returns: success, invitation_id and email_sent, which says whether the invitation email actually went out.

• When members plus pending invitations reach your plan's limit the call answers 402 plan_limit_reached with limit and current. A plan without role differentiation (Starter) accepts only the admin role, and any other role answers 402 plan_feature_required.
• The call answers 409 when the person already belongs to an organization, this one or another, or has a pending invitation to any organization: one person has one organization and one open invitation.
• The invitation expires after 7 days. Its link takes the invitee to sign-up, where they join this organization.

team_invite_resend

Sends the email of a pending, unexpired invitation again, with the same link. It does not extend the invitation's 7 days.

Changes data · scope team.write · roles: owner, admin · Pro and Enterprise plans

Returns: success and email_sent, which says whether the email actually went out.

• An unknown invitation answers 404, one that is no longer pending (accepted or cancelled) answers 400, and an expired one answers 410: cancel it and send a new one.

team_invite_cancel

Cancels a pending invitation so its link can no longer be accepted. This cannot be undone: to invite the person again, send a new invitation.

Deletes or overwrites data · scope team.write · roles: owner, admin · Pro and Enterprise plans

Returns: A confirmation, success: true.

• Only a pending invitation can be cancelled; any other (an accepted one, say) answers 400. Cancelling gives the seat back to your plan's limit.

Organization settings

These details are printed on quotations and their documents, and only the owner may read or change them. The logo and stamp images have their own upload tools, such as `settings_logo_upload_url_create` and `settings_stamp_upload_url_create`.

settings_get

Returns the organization's details as printed on quotations: names, registration numbers, address and contact details, and the defaults for new quotations. Owner only.

Read-only · scope settings.read · roles: owner · Pro and Enterprise plans

No parameters.

Returns: The organization record: name, legal_name_ar, legal_name_en, cr_number, cc_number, sfda_license, vat_number, address_ar, address_en, phone, fax, po_box, city, postal_code, the default fields and quote_number_prefix, plus logo_path and stamp_path, which show whether the two images exist.

• Even reading is limited to the owner: any other role answers 403.
• logo_path and stamp_path are read-only here. The images are uploaded or removed with the logo and stamp tools.

settings_update

Changes the organization's text details and the defaults for new quotations. Only what you send changes, and an empty string clears a field. Owner only.

Changes data · scope settings.write · roles: owner · Pro and Enterprise plans

{
  "cr_number": "1010123456",
  "vat_number": "300012345600003",
  "default_quote_validity_days": 30,
  "default_payment_terms": "net_30",
  "quote_number_prefix": "ACM-"
}

Returns: A confirmation, success: true.

• A text field is cleared with an empty string or null. name, quote_number_prefix and the day counts cannot be cleared.
• Existing quotations keep the details they were printed with when they were made, and a change reaches new quotations only.

Your profile

Both tools work on the member who connected, the person every write is attributed to.

profile_get

Returns the profile of the member who connected: name, email and mobile number, along with their organization, the connection's scopes, their role, the organization's plan and what the role may do.

Read-only · scope settings.read · all roles · Pro and Enterprise plans

No parameters.

Returns: user_id, org_id, scopes, role, plan (with tier and features), capabilities (what the role may see and manage, such as can_view_bid_pricing), first_name, last_name, full_name, phone_number and email.

• plan.features shows what the organization's plan includes. A tool that belongs to a feature the plan lacks answers 403 plan_upgrade_required.
• capabilities sums up what the role can do: see prices, supplier quotes, deliveries and orders, and edit bids and products.
• A key whose owner has left the organization answers 403 on every call, not on this tool alone, and an admin has to issue a new one.

profile_update

Updates your own profile: first name, last name and mobile number. The number doubles as your salesperson contact on quotations, and the platform recognizes you by it, for example when approving WhatsApp group join requests.

Changes data · scope settings.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "first_name": "Layla",
  "last_name": "Hassan",
  "phone_number": "+966501234567"
}

Returns: A confirmation, success: true.

• The full name is derived from the first and family names. An invalid number answers 400, and so does a call that carries no field.
• Sales roster entries linked to you update with your profile, while quotations already made keep the contact details printed on them.

Zoho Books connection

Each organization uses its own Zoho API client. An owner or admin enters that client and connects under Settings → Integrations in the app, because the client secret never passes through these tools and access is granted on Zoho's own page. Once connected, the sync is managed with these tools. It runs every hour and never deletes a record on either side.

zoho_books_get

Shows whether Zoho Books is connected, the Zoho Books organization in use, which directions are on, the start date, and the last run's outcome and counts.

Read-only · scope settings.read · roles: owner, admin · Pro and Enterprise plans

No parameters.

Returns: An object with connected, zoho_organization_name, import_sales_orders, import_mode, export_sales_orders, export_quotations, sync_since, last_sync_at, last_sync_ok and last_sync_summary. No access token is ever returned.

zoho_books_organizations_list

Lists the Zoho Books organizations the connected login reaches, so you can choose the one to sync with.

Read-only · scope settings.read · roles: owner, admin · Pro and Enterprise plans

No parameters.

Returns: An organizations list, each with organization_id and name.

zoho_books_settings_update

Chooses the Zoho Books organization and turns sync directions on or off. Only what you send changes.

Changes data · scope settings.write · roles: owner, admin · Pro and Enterprise plans

{
  "import_sales_orders": true,
  "import_mode": "files",
  "export_quotations": true
}

Returns: The connection after the change, as zoho_books_get returns it.

• No direction can be turned on before an organization is chosen; the call answers 409.

zoho_books_sync

Runs the sync now instead of waiting for the next hourly run, and returns what it did.

Changes data · scope settings.write · roles: owner, admin · Pro and Enterprise plans

No parameters.

Returns: A summary with the counts of orders and files imported and sales orders and quotations sent, and one line per record Zoho refused.

• Answers 409 while another run is going or when no direction is on.

zoho_books_disconnect

Revokes ProcDuck's access to Zoho Books, stops the sync and deletes the organization's stored client secret. Nothing already copied is deleted on either side.

Deletes or overwrites data · scope settings.write · roles: owner, admin · Pro and Enterprise plans

No parameters.

Returns: A confirmation, disconnected: true.

• Reconnecting is done in the app only, and never copies a record twice.