QQCatalyst API & Orange Partner Program: Developer Help Guide

This guide answers the questions developers and agencies most often ask us when they connect a tool to QQCatalyst (QQ). It is based on partner and customer email threads (Feb-Oct 2026). Customer names and personal contacts are left out.

How to read it: each section is a set of short questions with direct answers, written the way a QQ API developer would answer you.

Quick start (5 steps)

  1. Request access from the Orange Partner Program mailbox (section 1). You will receive a Client ID, Client Secret and a callback URL.
  2. Send us your real callback URL if you are building a web app or using a no-code tool. Each credential set has exactly one callback (section 2).
  3. Sign in through the browser at the authorize URL and exchange the returned code for a token. Use the Authorization Code flow (section 2).
  4. Call the API from your server (not directly from a browser or mobile client) with Authorization: Bearer <token>. This avoids CORS issues (section 2).
  5. Stuck? Check section 3 (auth errors and fixes), then email orangepartnerprogram@vertafore.com.

Glossary

TermMeaning
QQ / QQCQQCatalyst, the agency management system
QQID, VIDYour QQ account identifier and your Vertafore ID. We ask for both when we issue credentials
Callback URL (redirect URI)Where QQ sends the browser after sign-in, carrying the authorization code
Authorization CodeThe OAuth flow QQ supports: browser sign-in, then code, then token
Orange Partner ProgramThe Vertafore program that handles API access requests
TenantOne agency's QQ account/database

Contents

  1. Getting started
  2. Authentication (OAuth 2.0)
  3. Troubleshooting auth errors
  4. Limits, throttling and security
  5. Syncing changes
  6. Data safety

1. Getting started

Key links

Q: How do I get API access?

A:

  1. Email the Orange Partner Program (orangepartnerprogram@vertafore.com). Tell us your use case: internal automation or a third-party product, which tools you'll use, and whether you need read-only or read/write.
  2. Agency Partnerships reviews the request. For an agency building something for its own internal use, this has not been a problem. We may ask whether you'll build it yourself or use a third party.
  3. QQ Support issues a Client Identifier, Client Secret and Callback URL, plus a getting-started PDF.
  4. For the QQ account that will authorize, we need:
    • first and last name
    • QQID
    • Vertafore ID (VID)
    • username (email format)
    • valid email
    • valid phone number

Credentials belong to a QQ account, not to a location.

Q: Does a third-party developer need anything extra?

A: Yes. If a third party builds on a customer's behalf, they must contact us directly and sign an NDA. Agency Partnerships sends it. If you use an AI or LLM service to build the integration, we recommend an enterprise or secure license so personal information is protected.

Q: Is there a sandbox?

A: We setup sandbox login and API credentials on request through the Senior Product Owner. There is no self-service option and sandbox provisioning is subject to case-by-case review.

Credential hygiene


2. Authentication (OAuth 2.0)

Use the Authorization Code grant. It is the only flow we document and support. client_credentials is not supported. The Password Credentials grant has worked for some people (for example in Postman, or until MFA was turned on), but it breaks with MFA/SSO accounts, has suddenly stopped working for others, and gives unhelpful errors (see section 3). Please don't build on it.

ItemValue
Authorize URLhttps://login.qqcatalyst.com/oauth/authorize?client_id={ID}&redirect_uri={URI}&response_type=code
Token URLhttps://login.qqcatalyst.com/oauth/token
Token request POST, with header:
Content-Type: application/x-www-form-urlencoded

and body parameters:
grant_type = authorization_code
code = the URL-decoded authorization code
client_id = your Client ID
client_secret = your Client Secret
redirect_uri = your registered callback URL
Client auth (client_id and client_secret) Send them either way. Both work:
Option 1 - Authorization header (preferred, most used): Authorization: Basic <base64(client_id:client_secret)>. In this case leave client_id and client_secret out of the body.
Option 2 - Request body: include client_id and client_secret as form parameters, as listed in the Token request row.
Use one option, not both. The values are case-sensitive in either case.
ScopeOptional. If your tool insists on one, use openid (or the placeholder none)
Access token life7 days, then it refreshes. Each refresh returns a new refresh token, and the old one is not invalidated
Using the tokenSend Authorization: Bearer <token>. You don't send the Client ID or Secret on API calls

Two ways to get a token

Both ways use the same Authorization Code flow. Sign in with the native QQ login (QQ username and password) in the browser step. VSSO / SSO sign-in is not supported during token generation. That user's permissions apply to every API call you make.

Way 1: From your application (your server)

  1. Redirect the user's browser to the authorize URL (see the table above).
  2. After sign-in, QQ redirects the browser to your registered callback URL with a code parameter.
  3. Your server receives the code and URL-decodes it before using it. The code in the redirect is URL-encoded (for example %2F instead of /, %3D instead of =), and sending it still encoded makes the token call fail with a 400 Bad Request.
  4. Your server POSTs the decoded code to the token URL right away, with the parameters from the "Token request" row. The code is single use and short-lived (around 60 seconds).
  5. Store the access token on your server and use it as a Bearer token on API calls.

To see this working end to end, use the sample app (QQOAuthSampleApiClient.zip, linked on the Helpful Links page) as a reference.

Way 2: From Postman

Postman can run the sign-in for you, so you don't have to copy the code or URL-decode it by hand. Use this to test your credentials or to get a token manually.

  1. Open Postman, create a new request and go to the Authorization tab.
  2. Set Auth type to OAuth 2.0.
  3. Fill in the configuration:
    FieldValue
    Grant TypeAuthorization Code
    Callback URLyour registered callback URL, exactly as registered with us
    Auth URLhttps://login.qqcatalyst.com/oauth/authorize
    Access Token URLhttps://login.qqcatalyst.com/oauth/token
    Client IDyour Client ID
    Client Secretyour Client Secret
    Scopeopenid (optional)
    Client AuthenticationEither option works: Send as Basic Auth header (preferred, most used) or Send client credentials in body
  4. After entering all the values, click Get New Access Token. Postman opens a window that redirects to the QQ login page.
  5. Sign in with your native QQ login (QQ username and password). VSSO / SSO sign-in is not supported.
  6. QQ asks you to authorize the application. Approve it.
  7. Postman generates the access token. Click Use Token.
  8. Use that token as a Bearer token (Authorization: Bearer <token>) to make API calls.

Q: What callback URL will I get?

A: By default we give you https://login.qqcatalyst.com/winformcallback/completed.htm. That works for desktop and Postman testing but not for web apps. Tell us your own callback URL and we'll register it.

Q: Can I register several callback URLs (dev, staging, prod)?

A: No. A Client ID/Secret pair supports exactly one callback. You have two options:

Q: My authorize request shows "An error has occurred". Why?

A: This usually means the callback in your authorize request doesn't match what is registered for your Client ID. Try these:

  1. Check that the redirect_uri in your request exactly matches the callback registered for your Client ID, with no extra spaces, placeholder text or different casing.
  2. Confirm that your callback was actually registered (or updated) for that Client ID. Only one callback is allowed per credential set.
  3. Make sure client_id is correct and in the right case, and that you sign in with a valid QQ user.
  4. If it still fails, contact us at orangepartnerprogram@vertafore.com with your Client ID (never the secret), the exact authorize URL you used, and the time of the attempt, and we'll check what is registered.

Q: Is there a headless server-to-server flow?

A: No. The documented Authorization Code flow is the only way to get a token, and there is no separate token-generation endpoint. Sign in through the browser to get the token, then make the API calls from your server (see the next question).

Q: Can my web or mobile app call the QQ API directly from the browser (client-server model)?

A: No, don't do that. Integrate with the QQ API through your own server, not directly from the client, to avoid CORS issues.

Q: Should I use one org-wide connection, per-user connections, or a dedicated integration user?

A: We recommend per-user connections, each using the same client credentials. Every action is then attributed to the individual user, and their QQ roles and permissions are respected automatically.

Q: What about MFA?

A: MFA is supported with the Authorization Code flow. Notes:

Q: Can I sign in with VSSO / SSO when generating the token?

A: No. We don't support VSSO (SSO) authentication during token generation. The recommended option is the native QQ login. Use a QQ user that has a native username and password to authorize, and keep that password to letters and numbers only (see section 3).


3. Troubleshooting auth errors

SymptomCause and fixes
400 Bad Request on /oauth/token (HTML body) Try each of these:
1. Use grant_type=authorization_code (not password or client_credentials).
2. URL-decode the authorization code before sending it.
3. Use the code immediately. It is single use and expires in about 60 seconds, so generate a fresh one if it was used or is old.
4. Send Content-Type: application/x-www-form-urlencoded.
5. Make sure redirect_uri is exactly the registered callback.
6. Check client_id and client_secret for typos and case.
7. Compare against the sample app (Helpful Links) or a working Postman request
401 Unauthorized on /oauth/token 1. Re-check the Client ID and Secret exactly as issued (case-sensitive, no spaces).
2. Try the other client-auth method (Basic header instead of body, or the reverse).
3. Confirm with us that the credentials and callback belong together
302 redirect to /Error.aspx?aspxerrorpath=/oauth/token (or 200 with an HTML login error) You are using the Password grant. Switch to Authorization Code (section 2)
"An unexpected error has occurred" / "An error has occurred" on authorize See the authorize-error answer in section 2: match redirect_uri to the registered callback, confirm it is registered, check client_id, sign in with a valid QQ user, then contact us
403 from a no-code tool but Postman works 1. Do the manual code exchange in Postman and use the Bearer token in the tool (workaround).
2. Compare the tool's raw token request with the working Postman request.
3. Use openid as the scope if the tool requires one.
4. There are no IP or non-browser restrictions on our token endpoint, so the tool's request is the place to look
Login works but nothing comes back after turning MFA on 1. Log out and sign in again in a new session.
2. Re-authenticate the QQ connection to get a new token.
3. Test the same call in Postman with the old and new token.
4. Remove extra scope or state parameters from the authorize URL and retest
Native login fails with special characters Change the QQ password to letters and numbers only, and use the native QQ login (not SSO)
GET v1/Customers/{id}/PersonalInformation returns 500 The customer is a Commercial customer. Use CustomerDetailSummary instead
404 on email/attachment endpoints Use entityType = Policy or Customer and a valid PolicyID or CustomerID

Tips

Note: older walkthroughs and some tools suggest the Password grant. If it fails, switch to Authorization Code.


4. Limits, throttling and security

TopicAnswer
Rate limit70 requests per second
Reducing callsUse bulk-style endpoints: POST v1/PoliciesInfo/ByPolicyIds and GET v1/Policies/{id}/PolicyInfo
PaginationDefined per endpoint, so check each endpoint's doc page. Parameters vary (page/rowCount vs pageNumber/pageSize)
User-agentWe don't block any today, but we may block specific user agents in future. Send a descriptive User-Agent and tell us what it is
Calling from a browserDon't call the API directly from client-side code. Route requests through your server to avoid CORS issues and to keep credentials private (see section 2)
WebhooksNone. Poll instead (see section 5)
Read-only accessEnforced by QQ user permissions, not by the API credentials (see section 6)

5. Syncing changes


6. Data safety

Q: Is there a "read-only" API credential?

A: No. API client credentials don't restrict what you can do. Authorization comes entirely from the user who signs in. For read-only behavior, create a dedicated QQ user with all create/edit permissions removed, and authorize with that user.


Questions? Reach out to orangepartnerprogram@vertafore.com for any questions.

Put these in your first message: exact URL, parameters, request and response bodies, timestamps with timezone, username, Client ID, and what you expected vs. what you got. A complete first message gets you an answer faster.


<