Integration requirements: What you need to gather for any build 

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. Let’s take a closer look at each, starting with the former.

Related: What are API connectors?

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

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.