# Introduction Server-to-server (S2S) data distribution is a mechanism for making audience data available for buyers within MediaMath. The data can be made available globally, so every MediaMath client can access it, or [permissioned](apis/audience-taxonomies/section/audience-segments-and-taxonomies/taxonomies-(permissioned) to a particular customer. The method for distributing the data is the same in both scenarios. The workflow is as follows: 1. [Sync](/guides/syncing) and store `MM UUID`, if using third-party (3P) cookie-based identifiers 2. Apply `Segment Code` to user 3. Inform MediaMath of `MM UUID`:`Segment Code` `MM UUID`: MediaMath Unique User ID (3P Cookie ID, Mobile Advertising ID, Connected TV ID). Note that in cases where 1P cookie IDs are being delivered to MediaMath, the `MM UUID` field in the examples below represents the 1P cookie ID value. `Segment Code`: The partner defined identifier for the segment. 32 bit integer is supported (maximum value of 2,147,483,647); if you are using a segment identifier that is not a 32-bit integer, declare [HashSegments: 1](/guides/server-to-server#data-transfer) in the file header to ensure proper processing and do the same when [creating your audience taxonomies](/apis/audience-taxonomies/permission-taxonomies/post_audience_segments). # Data Transfer ## Batch file based transfer Once a sync tag is in place, it is possible to start sending data to MediaMath. During initial setup, you will be asked to provide a sample file for validation by MediaMath. After validation, files will be processed automatically, on a regular basis. We ask that the contents be efficient to process (this is explained in more detail below). **Note:** There are [limits to the file size and the number of files](http://www.mediamath.com/legal/terms/datadelivery/) that can be sent. Sizes below represent gzip file sizes. 1. The size of any one file may not exceed 4 GB. 2. A maximum of 20 files may be sent per hour. 3. We enforce a total limit of 5 GB of files that can be sent per day, e.g. if you send us 10 files in a day, the sum of the sizes of all the files cannot exceed 5 GB. ## SFTP Audience data is uploaded by the provider to a MediaMath-supplied SFTP (file transfer for the secure shell—SSH—protocol) account. The server details are: | Name | Value | | --- | --- | | `Host` | sftp.datasvc.mediamath.com | | `Port` | 2222 | | `Protocol` | SFTP | | `Username` | *Supplied by MediaMath* | | `Password` | *Supplied by MediaMath* | It is highly recommended you use an SFTP client other than the Linux BSD 'sftp' command or a library that depends on it. LFTP has been thoroughly tested and can upload files using one of these single or multi file commands: ``` lftp sftp://username:password@sftp.datasvc.mediamath.com:2222 -e "put AgencyName_PartnerName_YYYYMMDDHHSS.log.gz; bye" lftp sftp://username:password@sftp.datasvc.mediamath.com:2222 -e "mput *.gz; bye" ``` ## Audience File If you are providing private client data (using a permissioned taxonomy or external data segment options) please include the client name in the filename, example: ``` AgencyName_PartnerName_YYYYMMDDHHMMSS.log.gz ``` If you are providing generally available data (using a global taxonomy) please omit the client name in the filename, example: ``` PartnerName_YYYYMMDDHHMMSS.log.gz ``` If you are providing both types of data, please provide 1 file for global data, and 1 file per private client, example (3 private clients and 1 global file): ``` AgencyName1_PartnerName_201407302300.log.gz AgencyName2_PartnerName_201407302300.log.gz AgencyName3_PartnerName_201407302300.log.gz PartnerName_201407302300.log.gz ``` The file supplied must contain unix line endings (`LF`, `\n`), and must be compressed with gzip. See [here](http://en.wikipedia.org/wiki/Gzip) for more information on gzip compression. ### Filenames The alphanumeric and special characters below can be used in filenames. Alphanumeric characters: - 0-9 - a-z - A-Z Special characters: - Underscore (_) ### Example File Format The audience upload file is a plain text file, containing a header section followed by rows of segment load statements, example: ``` Version: FileIdentifier: DateCreated: UserNamespace: UserTableId: SegmentNamespace: Mobile: <0/1> HashSegments: <0/1> HashIDs: <0/1> CookieorDeviceID SegmentCode:UnixTimestamp SegmentCode:UnixTimeStamp SegmentCode:UnixTimeStamp ... CookieorDeviceID SegmentCode:UnixTimestamp SegmentCode:UnixTimeStamp SegmentCode:UnixTimeStamp ... CookieorDeviceID SegmentCode:UnixTimestamp SegmentCode:UnixTimeStamp SegmentCode:UnixTimeStamp ... CookieorDeviceID SegmentCode:UnixTimestamp SegmentCode:UnixTimeStamp SegmentCode:UnixTimeStamp ... CookieorDeviceID SegmentCode:UnixTimestamp SegmentCode:UnixTimeStamp SegmentCode:UnixTimeStamp ... CookieorDeviceID SegmentCode:UnixTimestamp SegmentCode:UnixTimeStamp SegmentCode:UnixTimeStamp ... ``` **Note:** The header section is followed by a blank line `Version` - The version of the MediaMath audience data onboarding system; this should be '3' for new integrations. `FileIdentifier` - Print the filename. This should be unique from other uploads and follow the naming convention above. `DateCreated` - Unix timestamp of file creation. For more information on Unix Time, see [here](http://en.wikipedia.org/wiki/Unix_time). Linux example: `date +"%s"` `UserNamespace` - Specifies whether the supplied User IDs are from the Partner Namespace, or from MediaMath (mm). If you are supplying MediaMath User IDs, obtained from our sync pixel, or device IDs this will be 'mm'. If you are delivering 1P cookie IDs, this will reflect the value provided to you by MediaMath for that 1P cookie ID. `UserTableId` - OPTIONAL: This is the ID used for identifying the match table for user IDs outside of the MediaMath namespace. This header should only be included when using a `UserNamespace` that is not 'mm' and user IDs that are not 1P cookie IDs. This the same value used in our sync pixel, for example: //pixel.mathtag.com/sync/img?mt_exid=*UserTableId* `SegmentNamespace` - Specifies whether the Segment Code values are from the Partner Namespace, or from MediaMath. Usually this is the Partner namespace assigned to you. `Mobile` - A value of 1 indicates that the User IDs in this file are Mobile or CTV device IDs, otherwise 0. Do not mix Cookie based and Mobile/CTV audiences in the same file. `HashSegments` - OPTIONAL: A value of 1 indicates that segment identifer is not a 32-bit integer, otherwise 0. `HashIDs` - OPTIONAL: **Only use this feature with express permission from MediaMath.** A value of 1 indicates that user ID values should be hashed upon upload, otherwise 0. A value of 1 should only be used if the user ID is not in [GUID Version 4 format](http://guid.one/guid). **Note:** There are 2 special cases for the UnixTimestamp value when used on the segment load statements | Value | Meaning | | --- | --- | | **0** | "Now"" - will add the user at point of processing | | **-1** | Remove user from specified segment | The UnixTimestamp can be used in regular form (seconds since Epoch), to define if a user should be added to a segment in the future or the past. This is useful for recurring purchases, or time sensitive deals. It also allows for the back processing of data, should the partner suffer from a failure. We request that you combine user/segment load statements, so that many segments are applied on a single line, rather than duplicating the same User ID on more than one line throughout the file. **Note:** As part of ongoing validation procedures, files will be checked for this efficiency. Failure to upload in a load efficient manner may lead to automatic processing being suspended until rectified. ## Quota The SFTP will not accept an upload larger than 4GB per file; this represents the gzipped file size. Each line must be fewer than 8,000 characters. Additionally, a maximum quota is defined to prevent partners de-stablizing the service. Currently this is a maximum of 5GB per day and 20 files per hour. These [quotas](http://www.mediamath.com/legal/terms/datadelivery/) are reset at midnight UTC and every hour on the hour respectively. ## Example File In this example, the Partner is using MediaMath cookie IDs, and has been assigned the `SegmentNamespace` 'ep'. ``` Version: 3 FileIdentifier: ExamplePartner_201407302300.log.gz DateCreated: 1406761200 UserNamespace: mm SegmentNamespace: ep Mobile: 0 2c3753c5-9a67-4600-f044-a5d7e0c5f6d7 10001:0 10003:0 10005:1406850980 3d3353c3-9a67-4651-a443-a6d7e1c4fde8 10002:-1 4e2754c5-5562-4601-1742-a9d7e2c3fef9 10002:0 ``` Example File Explanation 1. Append segments 10001 & 10003 right now, 10005 with an historical UNIX timestamp 2. Remove user from segment 10002 now 3. Add user to segment 10002 now ## Mobile & other Connected Device Audiences Every Android and Apple device (>= iOS6) has a unique identifier. The process for uploading audience files is exactly as above, except that instead of a 3P Cookie ID, the IDFA or GAID is used. Similarly, other connected devices - like TVs - have unqiue identifiers. When sending non-cookie based audiences, ensure the header of the file declares `Mobile: 1`. While Apple's iOS advertising IDs are typically all in upper case and Google's Android advertising IDs are typically all in lower case, we don't distinguish between case during the data onboarding process. Do not mix cookie and non-cookie based audiences in the same file. ## Processing Log API You may query the following API endpoint to get job results: ``` https://s2s-api.datasvc.mediamath.com/logs ``` You must use Basic Authentication, with the same user credentials as your SFTP. We recommend implementing retry logic with exponential backoff. Queries can be executed as follows, all variables should be URL encoded ``` https://s2s-api.datasvc.mediamath.com/logs?filename=ExamplePartner_201407302300.log.gz https://s2s-api.datasvc.mediamath.com/logs?start_date=1970-01-01%2012:00:00 https://s2s-api.datasvc.mediamath.com/logs?start_date=1970-01-01%2012:00:00&end_date=2000-01-01%2023:59:59 https://s2s-api.datasvc.mediamath.com/logs?offset=100 ``` The processing logs will be returned in JSON format. Use the offset paramater for pagination. Messages include: - OK - File is empty - File is invalid - File is not in GZIP format - Invalid headers - Integration {x} is not authorized to write into namespaces {y} Another example on a linux command line: ``` curl -u : https://s2s-api.datasvc.mediamath.com/logs?filename=ExamplePartner_201407302300.log.gz | python -m json.tool ``` ## Taxonomies & External Data Segments There are two ways to expose the audience segments onboarded in MediaMath Platform: **Taxonomies** - These can be global, meaning all MediaMath customers will have access to the segments within the taxonomy via MediaMath Platform. - These can be permissioned so that only select MediaMath customers have access to the segments within the taxonomy in MediaMath Platform. **External Data Segments** - These represent a single segment of users and are always permissioned. - These are also referred to as Data Pixels. It’s possible to use both methods to achieve a mix of [global and permissioned taxonomies & external data segments](/apis/audience-taxonomies/section/audience-segments-and-taxonomies) to suit your needs and the needs of your customers. Note: The S2S data import process is the same for both global and permissioned taxonomies, as well as external data segments.