HaloPSA

Step 1: Create a read-only roleCopy Anchor Link

The application in Step 3 signs in as an agent, and HaloPSA only ever shows the application what that agent's role allows. A dedicated role keeps the integration scoped to exactly the data it reads. Anything not listed below stays Not set.

In HaloPSA, open Configuration → Teams & Agents → Roles and click New.

1. Details tab – Role Name: Cotillion Read-only.
2. Departments & Teams tab – Membership level to all Departments: View all (Can view all Tickets in all Departments). Opportunities are tickets in HaloPSA, so this is what lets the integration see every deal, without the right to change one.
3. Permissions tab:
   • General Permissions – Is a HaloPSA Administrator: No.
   • Feature Access – Read Only on each area Cotillion reads:
     • Tickets Access Level – the opportunities and their actions (the notes on each deal), and your projects and service tickets for the Trust Profile: in HaloPSA a project is a ticket too.
     • Sales Access Level – the opportunity pipeline and its stages.
     • Customers Access Level – customers and their sites.
     • Users Access Level – the contacts at each customer and on each deal.
     • Quotations Access Level – the quotations on each opportunity and their lines.
     • Products Access Level – the items your quotation lines sell.
   • Tickets Permissions – Can view Unassigned Tickets: Yes; Can view Tickets that are assigned to other Agents: Yes.
   • Type Restrictions – Allow use of all Ticket Types: Yes.
   • Client Restrictions – Allow use of all Customers: Yes. A customer the role cannot see is a customer whose deals Cotillion cannot sync.
   • Billing Permissions – Can View Item Costs, Can View Item Prices and Can View Product SKU: Read Only. These are the cost, price and vendor SKU of each line, which a vendor registration carries.
4. Save.

Step 2: Create an API agentCopy Anchor Link

1. Open Configuration → Teams & Agents → Agents and click New.
2. Set Username to Cotillion API and tick Is an API-only Agent. An API-only agent takes up no licence and cannot sign in to the web or mobile app, so leave Email Address empty.
3. Roles: Cotillion Read-only (Step 1), and no other role – an agent takes the highest permission of all its roles.
4. Default Team: None. The field is required, but what the agent sees comes from the role, not from a team.
5. Save.

Step 3: Create the API applicationCopy Anchor Link

1. Open Configuration → Integrations → HaloPSA API → View Applications and click New.
2. Fill in the Details tab:
   • Application Name: Cotillion
   • Active: ticked
   • Authentication Method: Client ID and Secret (Services)
   • Login Type: Agent
   • Agent to log in as: Cotillion API (the agent from Step 2)
3. On the Permissions tab, tick exactly these, and nothing else (leave all, all:standard and all:teams unticked – they grant more than the integration reads):
   • read:sales – the opportunities: stage, status, value, probability, dates, owner and custom fields; and their actions, the notes on each deal.
   • read:customers – customers, their sites, and the contacts at each customer and on each deal.
   • read:quotes – the quotations on each opportunity and their lines.
   • read:tickets – your projects and service tickets, which the Trust Profile reports as delivered projects and SLA results.
4. Webhooks: the one grant that is not read. Also tick admin:webhooks. This is how HaloPSA tells Cotillion that an opportunity was created, changed status or closed: Cotillion registers a signed webhook pointing at its own endpoint, limited to your opportunity ticket types, and removes it again when you disconnect. It registers nothing that points anywhere other than Cotillion. With this permission withheld the integration still works (every change is then found by the normal 5-minute sync instead of being announced).
5. Leave the Security tab as it is: Cotillion calls HaloPSA from its servers, not from a browser.
6. Save, then copy the Client ID and the Client Secret.

Step 4: Find your tenant nameCopy Anchor Link

Your tenant name is the first part of the address you use to open HaloPSA: for https://acme.halopsa.com it is acme. That is the only part of the address Cotillion asks for; it builds the API and sign-in addresses from it.

Step 5: Connect in CotillionCopy Anchor Link

1. Sign in to your Cotillion workspace at cotillion.indyrct.com.
2. Open CRM / PSA in the sidebar → Connect → HaloPSA.
3. Enter your tenant name, Client ID and Client Secret from the steps above.
4. Click Test & Connect.

What happens automatically:

• ✅ Cotillion builds your HaloPSA address and its sign-in address from your tenant name.
• ✅ Verifies the credentials against the HaloPSA REST API.
• ✅ Encrypts them with an AWS KMS envelope before storing.
• ✅ Starts a one-time backfill sync, then schedules recurring updates.

Step 6 (optional): Exclude individual opportunities from the syncCopy Anchor Link

Some opportunities should never appear in Cotillion: internal-only forecasts, experiments, or deals you don't want surfaced for vendor registration. You can opt them out with a custom field on the opportunity.

In HaloPSA:

1. Open Configuration → Custom Objects → Custom Fields and click New.
2. Fill in the field:
   • Field Name – CotillionExcludeFromSync (HaloPSA adds CF in front).
   • Field Label – Cotillion Exclude From Sync (must match exactly: Cotillion looks for this label).
   • Type of Field – Checkbox.
3. Save.
4. Open Configuration → Sales → Ticket Types. Every type listed there is a kind of opportunity (a new instance has Lead, Opportunity and Quick Quote). Open each one and go to its Field List tab. Click Add under the list, keep Add Fields selected, pick Cotillion Exclude From Sync in Fields to add, click Add, then Save. Save the type as well, so the field shows on every opportunity.
5. Tick it on any opportunity you want hidden.

On the next sync (within ~5 minutes), Cotillion skips that opportunity entirely.