Blog


View all posts

Documentation Needs to Clearly State the Required Data Points

Ryan Gauss
Posted on
By , VP of Product Development


When a company receives integration documentation from a partner for either a programmatic or Server to Server (S2S)/API integration for ad requests, the documentation usually details what information is required and what is optional. A company building their integration from this documentation would surmise they would be compliant if they included the required elements and as many of the optional elements as possible. Unfortunately this is not always the case.

Many times elements listed as optional or recommended are actually required and this is where the confusion for developers comes in. A company will finish the integration and then reach out to the partner to inform them that they are ready to begin testing and then learn that the partner expects specific elements to be present in the connection even though they are listed as optional. The outcome is that the developer has to go back and spend additional resources to modify the connection to meet the new requirements.

The partner could have avoided a lot of this confusion and back and forth if they had been up front in the beginning about what elements are absolutely required.

This approach appears to be easy to accomplish, but it can become murky because some partners may fill ad requests at a much lower rate if certain optional elements are missing. So even though they are listed as optional they can impact the fill rate performance. In addition, some partners list elements as required because they will never fill a request if they are not present, but other parters may still fill a request without a required element but at a much lower rate. These differences in performance make it confusing to accurately interpret partner integration documentation.

So what is a developer to do as they attempt to interpret and navigate the various integration documentation they receive?

The best solution is communication. Ask questions and clear up any confusion prior to developing the connection. This is not a foolproof approach and can still require modifications but it can cut down on the back and forth. One helpful approach is to ask up front which of the optional elements are actually required and which ones will impact fill rate the greatest if not present. The partner documentation most likely lists a lot of elements that most companies will be unable to provide, so the company needs to identify which ones have the greatest impact on the fill rate and ensure they are included.

Partners have different definitions for what required, recommended and optional means in regards to integrating a connection with them. In order to limit the back and forth changes, it is best for the company to ask as many questions up front about anything they are confused or uncertain about. On the other side, partners need to make sure their documentation is accurate and current and clearly spells out how elements listed as optional or recommended can impact the the fill rate if not provided.