Developer's Guide
API Documentation
About the API

Our API serves as a powerful tool for integrating with external applications, facilitating seamless data transfer between systems like OneHQ and other applications. It utilizes GraphQL, which is an open-source query language and runtime. If you're new to GraphQL, learn more about at https://graphql.org/. Documentation for our GraphQL API is available at http://agencieshq.com/docs/graphql/index.html.

Webhooks
About the Webhooks feature

A webhook is an HTTP request that is automatically triggered by an event in a source system and sent to a destination system, often including a payload of data. Webhooks streamline automation by being instantly dispatched whenever the specified event occurs in the source system.

In other words, whenever a user creates, updates, or deletes a record in HQ, these events will automatically notify the destination system to perform the corresponding action on their end.

Configuring Your App to Handle Webhook Requests

To process webhook requests in your own app, you will have to configure the following:

  1. A publicly accessible URL (endpoint) that your webhook provider can send HTTP requests to.
  2. A custom application code that runs in response to new HTTP requests sent to this endpoint. For example: sending notifications to Slack or email, updating a database, or making another API call. You can even send another HTTP request to a different system, effectively creating a webhook of your own.

Most modern webhook providers send events via HTTP POST requests with a JSON payload.

Occasionally, providers will send events using a different payload type (XML or URL-encoded form data) or using an HTTP GET request, with data encoded in the path or query string parameters.

If you’ve ever written code to handle HTTP requests, you can process webhook events.

If you haven’t worked with HTTP requests before, we recommend taking a look at this glossary or reading this helpful guide to learn more.

You can find more information about Webhooks here.

How to access Webhooks feature

Important: The features and options shown in this menu may include functionalities that are exclusive to our Client Success Team, and may not be accessible to all users.

Note that this section is only accessible to users with access to the HQAdmin app.

Locate and click on the Settings icon on the left-hand sidebar.

Within the Settings Dashboard, head to the Webhooks section.

Adding a new Webhook

Once on the Webhooks section, click on the <Add> button to create a new Webhook entry.

You'll see a new Webhook window on your screen. Here, you can enter all the necessary information to set up your webhook.

To streamline navigation, we've categorized webhook information into distinct sections. Below, you'll find a detailed breakdown of each section's fields. Mandatory fields are marked with "*".

In the Basic Info section, you will find the following fields:

  • Name: Enter a name for the destination system or endpoint.
  • Description: Enter a brief description about the destination system or endpoint.
  • URL*: This field is where the URL of the destination system or endpoint should be entered.
  • Request Method Type: This drop-down allows you to specify the request methods to indicate the desired action to be performed for a given resource.
  • Delete: The DELETE method deletes the specified resource.
  • Get: The GET method requests a representation of the specified resource. Note: Requests using GET should only retrieve data.
  • Head: The HEAD method asks for a response identical to a GET request, but without the response body.
  • Options: The OPTIONS method describes the communication options for the target resource.
  • Patch: The PATCH method applies partial modifications to a resource.
  • Post: The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server.
  • Put: The PUT method replaces all current representations of the target resource with the request payload.
  • Placeholder: The placeholder drop-down will be available once you select the resource in the following steps. Placeholders are available to use in the URL and will be replaced by the corresponding value when sent. Each placeholder must be surrounded by two sets of curly braces. Choose between the available placeholders and they will be added to the URL. Example: https://test.com/{{Id}}/update
    • Preview: This is a testing environment.
    • Staging: The staging site, exclusively accessible to our Client Success Team, replicates information from production to establish a dedicated testing environment.
    • Production: This is the live environment, representing the operational site. Please select this option.
  • Signing Secret:After saving the webhook, a "Signing Secret" field will appear with a code. This code serves as a security measure to ensure that you receive the same code on your end.

Auth Settings and Test Auth

This section allows you to configure authentication settings that enable the webhook to securely communicate with external systems:

  • API Key: Select this option to authenticate requests made by the webhook to external APIs or services using API Keys.
    • API Key: Enter the API Key.
    • Authorization Header Prefix: Specify the prefix where the API Key will be included.
    • Save & Test Button: Click this button after setting up the API Key to save your changes and perform a test.
    • Test Response: This field displays the response received after clicking the 'Save & Test' button.
  • OAuth: Select this option to authenticate requests made by the webhook to external APIs or services using OAuth Tokens.
    • Url: Enter the URL link for the endpoint.
    • Grant Type: Select the method through which the application obtains the access token.
      • client_credentials: This type is used by clients to obtain an access token outside the context of a user. This is typically used by clients to access resources about themselves rather than to access a user’s resources.
      • implicit: This type is used for native apps and JavaScript apps where the access token is returned immediately without an extra authorization code exchange step.
      • authorization_code: Select the method through which the application obtains the access token.
      • password: This type is a way to exchange a user’s credentials for an access token. Because the client application has to collect the user’s password and send it to the authorization server.
    • Token url: This field specifies the endpoint where the client application exchanges an authorization grant (like an authorization code or credentials) for an access token.
    • Authorize url: This field specifies the endpoint where the end-user authorizes the client application to access their resources. Typically, after the user grants permission, the OAuth provider redirects back to the client application with an authorization code or access token.
    • Client ID: The Client Secret should be found in the external system.
    • Client SECRET: The Client ID should be found in the external system.
    • Test Response: This field displays the response received after clicking the 'Save & Test' button.
    • Redirect URI: This is the endpoint to which the authorization server redirects the user after authentication. It’s where the authorization code or access token will be sent.
    • Authorization Code: The authorization code found in the external system.
    • Username: The username used in the OAuth authentication type.
    • Password: The password that pairs with the external system or the OAuth authentication type.

    Note: If you select the 'authorization_code' Grant Type, the Redirect URI, Authorization Code, and Password fields will become visible.

    Note: If you select the 'password' Grant Type, the Username and Password fields will become visible.

    Want to dive deeper into OAuth? Learn more here.

  • None: Choose this option if you prefer not to configure any authentication settings.

    • In the Headers section, you will find the following fields: Key and Value.

    These values can be sent to the URL of the destination system or endpoint as headers. For example: you can set the Key field as “Source” and the Value as “Advisor,” which will send this information to your endpoint as headers.

The Add a resource section is where you can select the resource that will trigger the Webhook.

Once you select the resource, the following new fields will appear:

  • Event Types: This drop-down list allows you to select the type of event that will trigger the webhook:
    • Create
    • Delete
    • Update
  • Custom JSON Checkbox: If you uncheck this box, the system will automatically send all the attributes.
  • Request body and Insert placeholder: This is where the package that will be sent to the endpoint should be entered in a JSON format. You can select the attributes from the Insert placeholder drop-down list.

The following is an example of a JSON package:

If there are any errors in the JSON package, the following message will be displayed:

Once you are done setting up the Webhook, click on the [SAVE] button at the bottom right side of the screen. You will be taken back to the Webhooks screen.

Activating a Webhook

Once on the Webhooks section, click on the URL link of the webhook you would like to activate.

You will be directed to the Basic Info section of the webhook. Click on the <Activate> button to enable it.

Pausing a Webhook

Once on the Webhooks section, click on the URL link of the webhook you would like to pause.

You will be directed to the Basic Info section of the webhook. Click on the <Pause> button to disable it.

Monitoring Webhook Events

You can check the Webhook Requests sent by HQ by clicking on the gears icon on the App Nav.

Within the Settings Dashboard, head to the Webhook Requests section.

Here, you can find all the webhook requests sent by HQ, including details such as request type, status, and body, among others.

SSO Instructions (Single Sign On)
About the SSO

Single Sign-On (SSO) is an authentication process that allows users to access multiple applications or services with a single set of login credentials. This simplifies the user experience by eliminating the need to log in separately to each application, enhancing convenience and security.

We offer two options for setting up this method:

  • Through OneHQ
  • Using our CAS (Central Authentication Service) API

Note: This feature is available exclusively to users with HQAdmin access.

Below are the instructions to configure SSO in your system using either method:

Option 1: OneHQ Single Sign-On Setup
  1. Log in to HQ Admin and set your Organization’s Service URL to the URL where authentication requests will come from.
  2. Configure your site to use a CAS client to authenticate with HQ SSO. There are many CAS clients and plugins online for popular languages and applications. See https://jasig.github.io/cas/development/integration/CAS-Clients.html for examples. 
    Server Hostname: hqssso.com
    Server Port: 443
    Server Path: cas
  3. Depending on your setup, you may have to map users on your site to users in OneHQ. (Note that OneHQ uses a numeric ID for the authentication username).
Option 2: Single Sign On CAS API

Below are instructions for obtaining tickets for authentication from our CAS API. Users must be created using the web interface before using the CAS API. An API for creating users is coming soon. The base URL for all requests is https://hqssso.com.

For testing, our staging server can be used: https://staging.hqssso.com.

  • Request a Ticket Granting Ticket

    • A Ticket Granting Ticket (TGT) is used to request service tickets for OneHQ applications. A TGT is valid for 8 hours and can be reused to request new service tickets.

    Sample Request:

    POST /cas/api/tickets
    username=username&password=password

    Sample Response:

    { "ticket": "TGT-1456351989bD48574D70A5DDB736" }
  • Request a Service Ticket

    • A Service Ticket (ST) is used to authenticate one time with an individual application. Once authenticated, the session will last as long as the TGT used to request this ST is alive.

    Sample Request:

    POST /cas/api/tickets/{TGT from previous request}
    service={service requested (e.g. https://agencieshq.com/users/service)}

    Sample Response:

    { "ticket": "ST-1456352402r82f0b620Ac73584530" }
  • Accessing OneHQ Applications with Service Ticket

    • Sample Request:

    GET https://agencieshq.com/users/service?ticket={ST}
  • Single Sign Out

    • A Service Ticket (ST) is used to authenticate one time with an individual application. Once authenticated, the session will last as long as the TGT used to request this ST is alive.

    Sample Request:

    DELETE /cas/api/tickets/{TGT}
The Email Sync Feature

This feature seamlessly brings your Microsoft Exchange or G Suite emails into your HQ system. This means you no longer need to switch between multiple platforms to view or respond to your emails. Say goodbye to email juggling! Streamline your workflow and save valuable time by managing all your emails in one place.

Note: This feature is available exclusively to users with HQAdmin access.

To start using this feature, follow the steps outlined below:

Step 1: Configuring Mail Flow or Transport Rules

When you set up the mail flow or transport rules on your end, OneHQ will securely receive a copy of your emails. The system will then identify emails that correspond to discussions initiated in OneHQ and integrate them into the system, displaying them on the corresponding records in HQ.

For Microsoft Exchange (Service)

Note: You'll need administrative access to Microsoft Exchange for the setup process.

  1. Navigate to the Admin section and configure the rules to include [youremaildomain]@forward.onehq.com in the BCC line for all incoming and outgoing emails. This ensures that emails sent and received by specified users are synced with OneHQ.
  2. You will need to set up two separate rules:
    • Incoming Email Rule: Apply this rule to emails where your users are in the "To" or "CC" fields.
    • Outgoing Email Rule: Apply this rule to emails where your users are in the "From" field.

For more comprehensive instructions on configuring Mail Flow Rules, please refer to the resource provided here.

For G Suite (Service)

Note: You'll need administrative access to G Suite for the setup process.

  1. Navigate to the Admin console and configure the rules to include [youremaildomain]@forward.onehq.com in the BCC line for all incoming and outgoing emails.
  2. Set up routing rules according to Google’s documentation specific to your domain or organization.

For more comprehensive instructions on configuring Mail Flow Rules, please refer to the resource provided here.

Sender Authentications SetUp

Ensuring the security and authenticity of your emails is essential for reliable communication. Sender Authentication is a vital step in this process, allowing recipients to trust the source of the emails they receive. This step-by-step guide will assist you in setting up SendGrid Sender Authentication for your domain.

Step 1: Gather Essential Details

Before you begin, you'll need to collect some vital information and share it with the Client Success Team:

  • Identify your Domain Name Server (DNS) host. Common examples include GoDaddy, Cloudflare, and Google Cloud.
  • Provide the domain name that requires Sender Authentication.
Step 2: Setup Initiation by OneHQ

Once you've provided your DNS host information and domain details, OneHQ will initiate the setup process on our end. You'll receive a confirmation email acknowledging the receipt of your information.

Step 3: Accessing Your Configuration Guide

Upon completion of the setup on our end, you'll receive an email containing a guide on setting up the necessary DNS records on your DNS host.

  • Access the guide provided in the email or click here to learn more about the DNS record configuration process.
  • If you have trouble accessing the link, you can find the required DNS records within the email for quick reference.

Once you've provided your DNS host information and domain details, OneHQ will initiate the setup process on our end. You'll receive a confirmation email acknowledging the receipt of your information.

Step 4: Configuring DNS Records on Your DNS Host

Now, it's time to configure the DNS records on your DNS host. Here's what you need to do:

  1. Log in to your DNS host account using your credentials.
  2. Navigate to the DNS management section within your account.
  3. Add the provided CNAME records to your DNS configuration. If you encounter difficulties, consult your DNS host's support documentation or contact their customer support for assistance.
Step 5: Verification and Assistance

After configuring the CNAME records, inform OneHQ about the completion. This step is crucial for verifying the changes from our end. Reach out if you encounter any challenges during the setup process – our Client Success Team is here to assist you promptly.

Step 6: Conclusion

Congratulations! You've successfully set up SendGrid Sender Authentication for your domain. Your emails are now sent securely and are recognized as authentic by recipients, enhancing your email communication's credibility and reliability.

Remember, if you encounter any difficulties or have questions during the process, don't hesitate to reach out to us. We're here to ensure your experience is seamless and secure. Happy emailing!

External Apps

External Apps is a feature that allows external applications to seamlessly update or create any mappable resources within AgenciesHQ using a dedicated HTTP URL.

In simpler terms, External Apps enables clients to create a custom-made API-like endpoint to update or create resources in our system.

Note: All requests must be in JSON format.

Note: This feature is available exclusively to users with HQAdmin access.

To start using this feature, you can follow the steps below.

Locating the External Apps Feature

Important: The features and options shown in this menu may include functionalities that are exclusive to our Client Success Team, and may not be accessible to all users.

Locate and click on the Settings icon on the left-hand sidebar.

Within the Settings Dashboard, head to the External Apps section.

Adding an External App

Once on the External Apps section, click on the <Add> button to create a new External App entry.

You'll see a new External App window on your screen. Here, you can enter all the necessary information to set up your endpoint in HQ.

In this screen, you will find the following fields:
  • Name: Enter the name of the origin app.
  • Description: Provide a brief description of the origin app.
  • User: Select an active user within HQ. Actions performed by the system will be attributed to this user in the "Updated by" field. In most cases, the chosen user would belong to the Support Team.

Once you're done entering all the information, click on the <Save> button. You will be redirected back to the External Apps screen. Refresh your browser, and you will see the newly added External App listed instantly.

To continue setting up the endpoints, click on the name of the External App you just created. Your screen will refresh automatically and take you to the Basic Info section.

Kindly take note that the Authentication section is currently unavailable as it is still under development.

On the Add IN Endpoint section, you will be able to find the following fields:

  • Name: This field allows you to name the endpoint. Please ensure that the name entered in this field does not include any spaces.
  • Environment:
    • Staging: The staging site, exclusively accessible to our Client Success Team, replicates information from production to establish a dedicated testing environment.
    • Production: This is the live environment, representing the operational site. Please select this option.
  • URL: After clicking the <Save> button, the URL is automatically generated using the endpoint name you provided.
  • Event Type: This drop-down list allows you to select the type of event that will be triggered by the External App:
    • Create: Creates new records.
    • Create or Update: Creates new records if no matches exist with existing data; updates existing records based on primary key mapping.
    • Update: Updates existing records if a primary key match is found.
  • API Key: Use this key to authenticate requests to the URL. The key is matched with the user's API Key and varies depending on whether you've selected the Staging or Production environment.

    • Note: Requests made without this API Key will be rejected.

  • Resource: Select the resource that will be created or updated by this endpoint. Once you select the resource, the <Enable Endpoint> button and an IN Endpoint #1 section will be displayed.
  • Endpoint Status: This field will display the Enabled or Disabled Status.
  • Batch Key: Use this field to pass multiple objects in a single request. For example:
 
{
    “Test” :[
         { 
             “id” :1,
             “name” : “jane”,
             “last” : “doe”
         },
         {
             “id” :2,
             “name” : “john”,
             “last” : “doe”
         }
     ]
}

Note: The JSON key should be entered in this field, such as "Test" in the above example.

  • Sync All Fields Checkbox: Selecting this option will replace all existing information with data from the external application. If unchecked, it will add rows or update existing records based on the Destination Field's "All Fields" options.

Click the <Save> button, you will be directed to the Settings section's Dashboard. Return to the External Apps tab, select the name of the External App you just created, and navigate to the newly appeared IN Endpoint #1 section to configure the Destination Fields.

Note: The number following the # corresponds to the sequential order of existing endpoints for this External App. As you create additional endpoints, new sections will appear labeled as IN Endpoint #2, IN Endpoint #3, and so on.

In here, you will be able to find the following fields:

  • Destination Field: The Destination Field refers to the specific field you intend to map. If you're updating a field under "All Fields," select the base field such as "All Fields Emails." Each attribute you plan to update requires a new row. For instance, "All Fields Emails Address" should have its own Parameter Field. See the example below:
“identity-profiles”:[
          {
             “id”:34860601,
             “emails”:[
                {
                    “type”:”EMAIL”,
                    “value”:”fede.d@onehq.com”,
                    “source”:”UNSPECIFIED”,
                    “timestamp”:1662388049799,
                    “is_primary”:true
                },
                {
                    “type”:”EMAIL”,
                    “value”:”fededaumas@gmail.com”,
                    “source”:”UNSPECIFIED”,
                    “timestamp”:1662388073196,
                    “is_primary”:true
                },
                {
                    “type”:”EMAIL”,
                    “value”:”test@onehq.com”,
                    “source”:”UNSPECIFIED”,
                    “timestamp”:1662388088216,
                    “is_primary”:true
                },
                {
                    “type”:”EMAIL”,
                    “value”:”third@onehq.com”,
                    “source”:”UNSPECIFIED”,
                    “timestamp”:1663339659643,
                    “is_primary”:true
                }
             ]
         }
     ]
  • Formula: This field allows you to manipulate the outcome of a value. For instance, if the result is a string "true," you can convert it to a boolean value. Keep in mind that the variable "result" holds the original value before applying the formula. Refer to the example below for clarity:
  • Parameter Field: This field is the path on your JSON to match the value you want to map. It uses the JSONPath library. For the "All Fields" fields, it is the path to the list ([]) key. Please refer to the screenshots above.
  • Custom Value: The value entered in this field will override the value set in the Parameter Field.

Type:

  • Primary: This is the parameter by which the resource you want to update will be identified.
    • Note: The 'All Fields' option cannot be designated as a primary setting. Additionally, there can only be one primary field.
  • Lookup: The system will attempt to locate the Destination Field based on the values marked as Lookup. These values can be defined using the Formula or Custom Value fields.
    • Note: If no Lookup value is set (through the Formula or Custom Value fields), the system will default to the value set in the Parameter Field.

If you would like to add more rows under the Settings section, click on the [ADD] button on the right.

Once you've finished setting up the endpoints, click the <Save> button.

Enabling or Disabling an External App

Once on the External Apps section, click on the URL link of the External App you would like to enable or disable.

You will be taken to the Basic Info section of the External App. Navigate to the IN Endpoint # section and click <Enable Endpoint> to activate it or <Disable Endpoint> to deactivate it.

Monitoring External Apps Events

Within the Settings Dashboard, head to the Incoming Requests section.

Here, you can find all the incoming requests received by HQ, including details such as application, request status, and data, among others.

If you have any additional questions or concerns, please feel free to contact your Success Team at any time.

Products
CRM - Customer Relationship Management
DMS - Distribution Management System
ICM - Incentives & Commission Management
Data Visualization
Portal
Resources
Case Studies
Developer's Guide
FAQs
Integrations
Launch
Newsletter
Release Notes
About Us
Our Company
Our Team
Contact Us
(913) 232-2375
sales@onehq.com
Copyright © 2025. OneHQ, LLC.