Meet unified writes

Is pushing data to your users’ third-party platforms critical for your product? Unified Writes with Merge let you build once to push data anywhere.

With Unified Writes, Merge is a truly Unified API: no other method or platform accommodates writing data programmatically across all users and integrations. 

In this blog, we’ll cover why we improved our Writes, what changes we made, and a few things Unified Writes allow you to accomplish. Be sure to dig into the guides we’re linking along the way — they’ll answer more technical questions and are built to ease you into Writes.

Unified Writes include:

• The /meta endpoint, which allows you to programmatically account for variability across any supported integration
• Data writes to non-standard fields using Merge’s Unified POST endpoints
• Debugging tools that work for you, with rich error messages and a powerful new tool

We’ve also released comprehensive guides for all things Writes. Use the list below as a jumping-off point if you want to start building right away.

Writes

1. Introduction
2. Related and Nested Writes

Programmatic Writes with /meta

1. Introduction
2. Programmatic Nested Writes with /meta
3. Templates and Conditional Fields

Troubleshooting Writes

1. Warnings and Errors
2. Debug Mode

And while this update is focused on POST requests, don’t worry: PATCH is on the way soon.

Why Are Data Writes Difficult?

Unified APIs like Merge exist, in large part, because of variability across different software platforms. 

When you read data from a Unified API, this platform-specific variability is either normalized into a common data model or ignored. (Through a platform like Merge, that ignored data is made accessible through a feature such as Supplemental Data). Because data from a Unified API is presented in a standardized (‘unified’) format you’re able to build once and be confident you’ve anticipated everything.

When you write data through a Unified API this variability cannot be ignored. Different platforms and linked accounts have different fields that are required to make a successful POST request. On the surface, there’s no ‘standardized’ way for a Unified API to account for variability. But for a truly unified experience, a developer should be able to build once and:

• Never worry about an edge case, whether across platforms or end-user linked accounts (even if data is outside of a common data model) 
• Send requests to a single endpoint, regardless of which fields are required by platforms or linked accounts
• Troubleshoot error messages in a standardized way and not have to rely on translating third-party error messages

Until now, no Unified or Universal API anticipated variability across end-users in an integration to make writing data a truly unified experience. 

Merge anticipates everything with Unified Writes.

What are the new improvements?

Here’s what you can now do with Merge’s Unified Writes.

The /meta endpoint: anticipate more, work less

You’re probably wondering “how do I anticipate variability across dozens of integrations and all of my customers?” Easy: /meta.

The /meta endpoint allows you to account for all variability across integrations and users for any supported Common Model. If you can POST to an endpoint, you can anticipate anything. That’s the power of /meta. 

/meta returns all fields, field types, and specific enum values unique to a given linked account. With that response in hand, you now know what is required and what is optional to POST a Merge Common Model.

Its response looks something like this:

‍

There’s a lot to learn with /meta and you can go from beginner to power user in no time in our Introduction to Programmatic Writes with /meta.

/meta highlight: Nested Writes create even more with less code

Merge has always supported pushing nested data for common use cases (see our guide to Related and Nested Writes).

Now, you can chain together /meta with Nested Writes to accommodate powerful new use cases. 

Find out what fields are supported with Nested Writes and how to pair them with /meta in our guide to Programmatic Nested Writes with /meta.

Never Miss an Edge Case - Write to non-unified fields using Merge’s Unified POST endpoints

A Unified API should never prevent you from POSTing data. If /meta surfaces required fields that fall outside of those in Merge’s Common Models, we’ve built out functionality that allows you to still POST to that endpoint. This way, Merge is never a blocker.  

Write to non-unified, required fields through:

• Integration-specific parameters
• Linked Account-specific parameters
• Input-conditional parameters 
• Learn more in our guide on Templates and Conditional Fields

Together, all three fields allow you to POST to any platform on behalf of any customer. 

If you’re looking for support for integration-specific or Linked Account-specific parameters for a given integration, then reach out to a member of our team on Intercom. We’re always looking to help you get started.

The 'Write' Way to Debug: Information-rich troubleshooting

We’ve streamlined debugging with Merge into two parts to make your life simpler.

First, we’ve standardized our error and warning messages. You now only have to know one common set of error messages, regardless of the third-party platform that error is coming from. These error messages show you what, where, and how things went wrong.

Every error message you’ll need to worry about is laid out in our guide to Writes Warnings and Errors References.

We’ve also added a new Debug Mode to all endpoints. Debug Mode returns the original error message from a third-party platform, as well as any requests between Merge and that platform. Combined with our updated error and warning capabilities, your troubleshooting will be a breeze.

Here’s an example of this in action:

‍

Read more about Troubleshooting Writes in our Guide.

What will you do with Unified Writes?

Depending on the fields you want to write and the third-party platforms you want to support, you’ll learn everything you need to know - from pushing updates to basic fields to programmatic form generation with /meta - from our Writes guides.

Here are a few use cases of what you can do in your product with these features:

Problem: You want to create a candidate object in an ATS, but need to link the candidate to an existing job opportunity.

Solution: POST a “Candidate” object, and use a related write to include the “Jobs” object.

Problem: You want to generate a form in your product that creates a candidate in your user’s applicant tracking system. You already know you want to get basic information about the candidate, as well as a relevant resume, but need to anticipate the fact that certain jobs have certain required fields to be filled out.

Solution: 

1. Use /meta to surface the fields that you want your applicant to fill out. Meta will allow you to account for the variability of required fields across integrations and linked accounts. Follow the /meta guide here
2. Generate a form based on the fields provided by /meta and your product requirements
3. Form a POST request for your Candidate object, and use a Nested Write to create the related Attachment object in the same POST request. See more in our Nested Writes with Meta guide here.

Problem: You’re getting an error back from Merge that says “ERROR,” which doesn’t feel very descriptive. 

Solution: Use the `debug_mode=on` parameter to receive logs of the exact response returned by the third-party API. You can learn more about Debug Mode here.

These use cases are meant to give you just a taste of what’s possible with Merge. Not sure if your use case is possible with Merge? Ping us on Intercom — we’re always happy to help point you in the right direction. 

See you in the next update.

‍