Using Hubspot’s API to Submit  Forms

The approach outlined here uses functions built-in to WordPress. If you’re not working within a PHP/WordPress environment, the approach still applies. You’ll need to swap out the wp_remote_post() method with a similar HTTP request API in your language.

HubSpot API Tokens

To submit to HubSpot API’s you’ll need a private app token, which will be sent with API requests as a Bearer authorization header. In this scenario, the “app” is the website or web application that will be making API requests.

Creating a New Private App

To create a HubSpot API token for working with the forms API, visit https://app.hubspot.com/private-apps/9999999 where 9999999 is the ID of your HubSpot installation. Alternatively, you can get to the same screen through the UI at Settings > Integrations > Private Apps. Next, click the Create a private app button to get started.

Setting App Scopes (or permissions)

The private app token you create for working with the Forms API will need to have the following app “scopes”. These are basically permissions you select when you create the token.

• forms
• forms-uploaded-files

Click the Create app button, and you’re done, you can copy and paste the app token provided once it’s saved.

If you want more information on this process, take a look at HubSpot’s documentation on working with HubSpot private apps.

API Form Submission Requests

Use this new private app token to work with the forms API by opening your newly created private app and then copy the Access token. This is the token you’ll use in API requests to HubSpot, the client secret is not needed for the forms API.

Simple HubSpot Form Example

For the example below, I’m using a basic HubSpot form with only three fields to keep it simple.

The objectTypeId Property

The objectTypeId property is a little confusing when working with the form fields portion of the payload. This is basically a reference to the type of object that this form field will map to within HubSpot. In most cases you’ll use the ID 0-1 for form fields that map to contact record properties like firstname, lastname, email, phone and other defaults that are built-in to HubSpot.

If you’re submitting information that doesn’t map to contact properties, then you’ll need to know definitions for all the possible values that can be submitted as the objectTypeId field property.

• Contacts: 0-1
• Companies: 0-2
• Deals: 0-3
• Tickets: 0-5
• Custom objects: 0-0000000. To find the ID value for your custom object, make a GET request to /crm/v3/schemas. This will provide a value in this format.
• Calls: 0-48
• Emails: 0-49
• Meetings: 0-47
• Notes: 0-4
• Tasks: 0-27
• Products: 0-7
• Line items: 0-8
• Quotes: 0-14
• Communications: 0-18
• Postal mail: 0-116
• Marketing events: 0-54
• Feedback submissions: 0-19

More information on these object types can be found in the HubSpot API docs under “Understanding the CRM”.

WordPress PHP Example

The following PHP function will make a HubSpot form submission using the Forms API. The concepts in this approach will also work in any other server-side language. The logic is deliberately basic and not complex, so hopefully it’s not too difficult to adapt it to your own use case.

/**
 * HubSpot API: Refer Friends & Family
 */
function hubspot_api_form_submission()
{
  // Configuration
  $portal_id = '0000000';
  $private_app_token = '000-000-00000000-0000-0000-0000-000000000000';
  $form_id = '00000000-0000-0000-0000-000000000000';
  $api_url = "https://api.hsforms.com/submissions/v3/integration/secure/submit/$portal_id/$form_id";

  // Context
  $ip_address = $_SERVER['REMOTE_ADDR'];
  $page_title = get_the_title();
  $page_url = "https://$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URI]";
  $hubspot_utk = isset( $_COOKIE['hubspotutk'] ) ? esc_attr( $_COOKIE['hubspotutk'] ) : null;

  // Form values
  $fields = [ [
    'objectTypeId' => '0-1',
    'name' => 'firstname',
    'value' => 'Kevin',
  ], [
    'objectTypeId' => '0-1',
    'name' => 'lastname',
    'value' => 'Leary',
  ], [
    'objectTypeId' => '0-1',
    'name' => 'email',
    'value' => '[email protected]',
  ] ];

  // Payload
  $payload = [
    'context' => [
      'hutk' => $hubspot_utk,
      'ipAddress' => $ip_address,
      'pageUri' => $page_url,
      'pageName' => $page_title,
    ],
    'fields' => $fields,
  ];

  // POST request to submit form
  $response = wp_remote_post( $api_url, [
    'data_format' => 'body',
    'body' => json_encode( $payload ),
    'headers' => [
      'Content-Type' => 'application/json; charset=utf-8',
      'Authorization' => "Bearer $private_app_token",
    ],
  ] );

  // Error handling
  if ( is_wp_error( $response ) ) {
    $error = $response->get_error_message();
    wp_send_json_error( $error, 502, JSON_PRETTY_PRINT );
  }

  // Successful response received, could still be a HubSpot API error
  $json = wp_remote_retrieve_body( $response );
  $body = json_decode( $json, true );

  // Check for 400 API errors returned by HubSpot
  if ( isset( $body['status'] ) && $body['status'] === 'error' ) {
    wp_send_json_error( $body, 400, JSON_PRETTY_PRINT );
  }

  // No problems, successful submissions to HubSpot form has been made
  wp_send_json_success( $body, 200, JSON_PRETTY_PRINT );
}

This will make a submission to a basic HubSpot form containing 3 fields:

• firstname
• lastname
• email

When used it serves as an JSON API for the sake of simplicity, but again this can easily be adapted for whatever you need. All you’ll need to do is replace the wp_send_json_error and wp_send_json_success with your own use case.

Sources & Citations

The following sources were used to create this article. Links are provided below as citations for reference. These may be useful to explore if you’re crafting advanced HubSpot and WordPress integrations.

• HubSpot docs on how to submit data to a HubSpot form w/authentication
• HubSpot objectTypeId types
• Creating HubSpot private app API tokens