How to collect every integration requirement

As you look to build either an internal or customer-facing integration, you’ll first need to gather certain types of information.

We’ll review what this information looks like so that you can build any integration successfully. But first, let’s align on the definition of integration requirements and why they matter.

What are integration requirements?

They’re areas your team needs to address when building to a specific 3rd-party API provider’s endpoint. Accounting for these areas successfully lets you build secure, performant, and reliable integrations.

These requirements typically fall in one of two buckets: technical and organizational. We’ll take a closer look at each after breaking down why integration requirements are critical.

Related: What are API connectors?

Why integration requirements are important

Every integration build is unique. 

API providers have different endpoints, rate limits, SDKs, and may offer different authentication and pagination methods. Without a deep understanding of each of these areas for a given build, you won’t be able to implement an integration successfully.

Equally important, you likely have unique integration requirements. Perhaps you need to build either a one way or bidirectional sync; or you need to sync data at a specific frequency; or you need the integrated data to appear in a certain format in the destination system.

In short, your team needs to make the effort of researching and documenting the requirements for every integration project so that they can be prepared to build it successfully from the beginning.

Technical requirements 

This typically includes the core facets of any integration build: endpoints, SDKs, authentication, pagination, and rate limits.

Endpoints 

Some API providers offer a broad range of endpoints that seemingly overlap or that can be easy to mix up. You’ll need to carefully review each in the provider’s API documentation so that you can pinpoint the best one for your integration scenario. 

In many cases, reviewing the sample responses can help you do just that.

For example, say you want to access time off policies for employees in BambooHR and you see the following:
‍

• A time off types endpoint: <code class="blog_inline-code">https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1/meta/time_off/types/</code>
• A time off policies endpoint: <code class="blog_inline-code">https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1/meta/time_off/policies/</code>

By reviewing a sample response like below for the time off policies endpoint, you can tell that it’s the one you want to use. 

SDKs

Most API providers offer software development kits (SDKs) to help you build integrations faster and more effectively within the programming language you and your team are most comfortable with.

To that end, you should review the API provider’s available SDKs (typically in language-specific package management systems), read though the instructions for importing a package into your code base, and learn how to use it after it’s installed.

Related: A guide to using SDKs

Pagination 

API providers offer different forms of pagination, whether it’s offset pagination, keyset pagination, cursor-based pagination, etc. 

Understanding which method(s) a given endpoint supports and how that method works is critical to ensuring that you structure your requests and process responses correctly.

Greenhouse, for instance, includes the URL for the next page of results within the response’s header, allowing you to call it automatically. 

Using their candidates endpoint as an example, the response header below shows the URL for fetching the second page of results, which includes 2 candidates.

<code class="blog_inline-code">Link: https://harvest.greenhouse.io/v1/candidates?page=2&per_page=2; rel="next"</code>

Rate limits

Every API provider offers a unique set of rate limits and presents them differently.

For instance, Greenhouse uses <code class="blog_inline-code">X-RateLimit-Limit</code> in its header to indicate the number of requests you can make to the endpoint in a given 10 second window; while GitHub sets rate limits by the hour (e.g., 5,000 requests per hour) and can provide a variety of headers in addition to <code class="blog_inline-code">X-RateLimit-Limit</code> to provide you with additional insights on your rate limit situation.

Understanding and following your rate limits across integrations consistently is critical to helping you build integrations that sync data frequently and reliably, as well as avoid additional costs.

Authentication and authorization

Like many of the other requirements, API providers typically offer varying approaches to authentication and authorization, whether that’s OAuth, API keys, or basic authentication.

You can spot these differences just from looking at a few similar tools. For instance, Lever lets you use OAuth, while Greenhouse, another ATS, only offers basic authentication (your username is your Greenhouse API token and you don’t need to provide a password).

You’ll need to review each API provider’s specific approach so that your integration requests are processed successfully. 

Organizational requirements 

Aside from the technical requirements, you’ll also need to consider factors like the engineering resources at your disposal, your plan for prioritizing integrations, and how you’ll take the integrations to market (in the case of product integrations).

Engineering resources

Each integration build takes tens of hours, and the work involved in maintaining an integration is never-ending; your engineers will likely need to spend a couple hours every week maintaining an integration. 

Given the level of resource investment that's involved, you’ll need to align on the engineers within your team who can build and maintain the integrations, the ones they’ll focus on, and how much time they should be spending on both implementation and maintenance.

Prioritizing integrations

Each integration offers unique business value. 

In the case of customer-facing integrations, for instance, some may help you increase your close rate, others may help you retain customers, and others still can help you expand to new markets. 

At the same time, every integration has a unique cost associated with it, whether that’s the direct cost of forming a partnership with an API provider or the resource cost in building and maintaining the integration.

Given the unique benefits and costs associated with each integration, you’ll likely need to develop an integration scorecard that helps you determine and prioritize the best opportunities.

Here’s how it can look for customer-facing integrations: 

Go-to-market strategy

In the case of customer-facing integrations, you’ll also need to decide on pricing each integration, marketing it, and supporting it.

• Pricing: If an integration is critical for every type of customer, it may be worth including it at no additional cost; while if an integration is only relevant to larger companies, it can make sense to tack on an additional charge

• Marketing: Various marketing activities can help you raise awareness and adoption of your integrations, from writing up blog posts to amplifying the integrations across your social channels to even announcing them in emails

• Support: You’ll need to decide who within your support team will support the integrations, the SLAs you’ll offer for specific issues, and more

How to gather integration requirements

Your team will need to ask themselves a certain set of questions to help them gather the requirements successfully. Here are just a few worth asking:

Does the API provider offer publicly-available documentation and a sandbox account for testing?

Hopefully, the answer is yes and you can move on to gathering more integration-specific requirements. 

But you might end up learning that you need to enter into a formal business partnership with the vendor before you can access either documentation or a sandbox account. Assuming that’s the case, you’ll need to put a pause on gathering additional requirements and work with your business development or partnerships team on forming a business relationship with that API provider (which will likely take time and require ample investment).

Related: A guide to integration partnerships

What resource do we need to access and what actions do we want to perform on it?

Once you’re able to answer this, you can review the API provider’s documentation to suss out the most relevant endpoint for that resource. From there, you can determine the parameters you'll need to pass, the HTTP method you should use (assuming they support it), the authentication and authorization details you'll need to access the resource, etc.

How frequently do we want to sync data?

Certain scenarios, like syncing data on new leads, may require real-time—or near real-time—syncs, while syncing, say financial documents with a file storage tool, can be a daily or even weekly sync.

You can confirm whether the API provider supports your desired sync frequency via their documentation. For instance, you can learn if they support real-time syncs for a given resource—via a webhook—within their documentation.

What error messages does the API provider typically use?

While many API error messages are standard across providers (e.g., “429 Too Many Requests”), others are more specific to a given provider. Understanding all of the ones you might see for a given integration can help you build more reliable error-handling processes upfront.

Who on the team is responsible for certain facets of an integration project?

An integration project often can and should require several stakeholders to get involved.

For example, maybe certain engineers should be responsible for the initial implementation, while other engineers should be responsible for maintaining that integration afterwards.

Whatever the case may be, you’ll need to craft and align on a plan that the relevant stakeholders can review and sign off on.

For a customer-facing integration: How will it be taken to market?

Your team will need to decide whether the integration should be available for “free” or if it should be included in a certain subscription tier(s). Moreover, your team will need to align on the processes for supporting the integration (e.g., the SLA for responding to issues), the marketing activities worth pursuing, when and how to introduce and speak about it during the sales cycle, and more.

‍Related: Our best resources for taking your integrations to market

Avoid dealing with complex integration requirements with Merge

Using Merge, the leading unified API platform, you can add hundreds of integrations to your product through a single integration build. 

This means you only have to worry about a single approach to rate limiting, authentication, and pagination—saving your engineers time and helping you take a wide range of integrations live quickly. 

Merge’s customer success team will also partner with you on taking your integrations to market successfully, whether that’s training your customer-facing teams or providing resources that can help you manage specific facets of your GTM strategy.

Learn more about how Merge can meet your customer-facing integration requirements by scheduling a demo with one of our integration experts.