{"_id":"56fc166905fd6e3400ed2e19","category":{"_id":"56cf3f866c5d7a13005ee894","__v":67,"project":"56c35c56c0c4630d004e864c","version":"56c35c56c0c4630d004e864f","pages":["56cf5bb88629f91300fd97c5","56cf5bf68629f91300fd97c7","56cf5fd2287eb20b009f9f37","56cf631a44c5700b0095c1c8","56cf63ae6c5d7a13005eeb58","56cf6408287eb20b009f9f40","56cf643a287eb20b009f9f43","56cf65ba336aa60b0086a435","56cf66df336aa60b0086a440","56cf69b344c5700b0095c1cf","56cf6a3d44c5700b0095c1d3","56cf6ac6336aa60b0086a44e","56cf6b298acacb13008148c9","56cf6cd68629f91300fd97e3","56cf6e048acacb13008148cd","56cf6eac336aa60b0086a455","56cf6edf287eb20b009f9f5a","56cf6f6b336aa60b0086a462","56cf704e8629f91300fd97f0","56cf70bf6c5d7a13005eeb6f","56cf72c6287eb20b009f9f76","56cf74c86c5d7a13005eeb7f","56cf75f5336aa60b0086a496","56cf76b68629f91300fd9801","56cf76da8629f91300fd9805","56cf776c8acacb13008148dc","56cf77ca6c5d7a13005eeb92","56cf788044c5700b0095c1fe","56cf78c28acacb13008148e5","56cf7a9544c5700b0095c207","56cf7b9b44c5700b0095c20c","56cf7c268629f91300fd980f","56cf7c456c5d7a13005eeba4","56d097b1376b040b005b3029","56d0992940d36e1d00bc13dd","56d099ed167e1e1b008079d2","56d09afa376b040b005b3032","56d09ba01ecc471500f1794a","56d09c13376b040b005b3034","56d09cde167e1e1b008079d7","56d09f30167e1e1b008079e2","56d0a00b376b040b005b303d","56d0a063167e1e1b008079e6","56d0a11a7c2e100b000af929","56d0b072167e1e1b00807a2e","56d0b0fb7c2e100b000af98b","56d0b16d1ecc471500f179af","56d0b1ee7c2e100b000af991","56d0b2407c2e100b000af998","56d0b2e640d36e1d00bc1456","56d0b3511ecc471500f179bc","56d0b3aab2cb7013004de65b","56d0b3d1b2cb7013004de65e","56d0b3fe7c2e100b000af9a1","56d0b4d67c2e100b000af9a5","56d0b52fb2cb7013004de666","56d0b59db2cb7013004de66c","56d0b621167e1e1b00807a4c","56d0b787167e1e1b00807a54","56d0b82d167e1e1b00807a55","56d0b8a8167e1e1b00807a5d","56d0b8fe167e1e1b00807a60","56d0b9951ecc471500f179c7","56d0ba55376b040b005b30a1","56d0bac31ecc471500f179cc","56d0bb6e167e1e1b00807a64","56d0bc95167e1e1b00807a6a"],"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-02-25T17:53:10.154Z","from_sync":false,"order":1,"slug":"buzz-api-reference","title":"Buzz API Reference"},"editedParams2":true,"parentDoc":null,"user":"56c39c05bc41330d009f25d7","__v":15,"version":{"_id":"56c35c56c0c4630d004e864f","project":"56c35c56c0c4630d004e864c","__v":8,"createdAt":"2016-02-16T17:28:54.864Z","releaseDate":"2016-02-16T17:28:54.864Z","categories":["56c35c57c0c4630d004e8650","56c7b9e5379b311700ed8fe3","56c7bab4606ee717003c4766","56c7bb3613e5400d001e8cbd","56cf3f5a5267d70b00494c4b","56cf3f866c5d7a13005ee894","56fd3956caad892200847bce","599da256e7742b002588bb02"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.5.0","version":"0.5"},"githubsync":"","editedParams":true,"project":"56c35c56c0c4630d004e864c","updates":["58507ce29d4f700f00e9dbbc"],"next":{"pages":[],"description":""},"createdAt":"2016-03-30T18:09:45.743Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"curl","code":"curl -X POST \"[host]/rest/segment_upload\" -b cookies.txt -d '{\"file_name\":\"user_data_sample.txt\",\"size_in_bytes\":412,\"account_id\":1,\"file_format\":\"DELIMITED\",\"segment_key_type\":\"ALTERNATIVE\",\"continent\":\"NAM\",\"user_id_type\":\"IDFA\"}'\n#\n# After the first POST, get the ID and add /upload/ID to the URL:\n#\ncurl -X POST \"[host]/rest/segment_upload/upload/1\" -b cookies.txt -F \"segment_file=:::at:::../user_data_sample.txt\"\n","name":"cURL example with single file upload"},{"code":"curl -X POST \"[host]/rest/segment_upload\" -b cookies.txt -d '{\"file_name\":null,\"size_in_bytes\":null,\"account_id\":1,\"file_format\":\"DELIMITED\",\"segment_key_type\":\"ALTERNATIVE\",\"continent\":\"NAM\",\"user_id_type\":\"IDFA\",\"segment_file_list\":[\"s3n://beeswax-data/user-list/customer_name/folder/part-00000\",\"s3n://beeswax-data/user-list/customer_name/folder/part-00001\"]}'","language":"curl","name":"cURL example with list of files"}]},"method":"post","results":{"codes":[{"status":200,"name":"","code":"{\n    \"success\": true,\n    \"message\": \"segment_upload created with ID = 1\",\n    \"payload\": {\n        \"id\": 1\n    }\n}","language":"json"}]},"settings":"","auth":"required","params":[{"_id":"56c38f9c2d97560d00e23cba","ref":"","in":"body","required":true,"desc":"The filename to be uploaded, including the extension. <255 chars, no spaces or special characters other than dashes and underscores.","default":"","type":"string","name":"file_name"},{"_id":"56fbf3200256470e0052538a","ref":"","in":"body","required":false,"desc":"The location of the file on the server. If this field is populated, Buzz assumes the file was already uploaded and will not allow further uploads. If absent, Buzz will auto-fill this when the file is uploaded in a subsequent POST.","default":"","type":"string","name":"path_to_file"},{"_id":"56fc13740256470e005253f3","ref":"","in":"body","required":true,"desc":"Size of the file to be uploaded, in bytes.","default":"","type":"int","name":"size_in_bytes"},{"_id":"56fc166905fd6e3400ed2e1d","ref":"","in":"body","required":false,"desc":"Not currently used.","default":"","type":"string","name":"datacenter"},{"_id":"56fc166905fd6e3400ed2e1c","ref":"","in":"body","required":false,"desc":"The type of file format expected. Valid formats are stored in the segment_file_format table.","default":"DELIMITED","type":"string","name":"file_format"},{"_id":"5bbfa2da7d1cb0000384b647","ref":"","in":"body","required":false,"desc":"When uploading multiple files of segment-user associations, a list of these files can be passed in a single POST. This will generally improve performance of the upload as well.","default":"","type":"array_string","name":"segment_file_list"},{"_id":"56fc166905fd6e3400ed2e1b","ref":"","in":"body","required":false,"desc":"Indicates whether the user IDs in the uploaded file should be put into a segment defined by the segment_key or the alternative_id from the segment. Must be set to either DEFAULT or ALTERNATIVE.","default":"DEFAULT","type":"string","name":"segment_key_type"},{"_id":"57ed39e394c0092000d3b559","ref":"","in":"body","required":false,"desc":"The destination continent data centers to upload the data. Only one continent may be specified per upload. If a segment is required across continents it must be uploaded twice. Options are NAM, EMEA, or APAC.","default":"NAM","type":"string","name":"continent"},{"_id":"56fc166905fd6e3400ed2e1a","ref":"","in":"body","required":true,"desc":"Indicates the type of IDs being imported, as defined in the \"segment_user_type\" view. Valid types include BEESWAX, CUSTOMER, IDFA, IDFA_MD5, IDFA_SHA1 , AD_ID, AD_ID_MD5, AD_ID_SHA1 , IP_ADDRESS, OTHER_MOBILE_ID","default":"","type":"string","name":"user_id_type"},{"_id":"594c39699d0a69001be663ae","ref":"","in":"body","required":false,"desc":"DEPRECATED. When set the segments associated with a user will overwrite all other user-segment associations for the given user. Use the operation_type field instead.","default":"0","type":"boolean","name":"overwrite"},{"_id":"594c39699d0a69001be663ad","ref":"","in":"body","required":false,"desc":"What action should be taken on these users. Commonly set to ADD_SEGMENTS or REPLACE_ALL_SEGMENTS","default":"ADD_SEGMENTS","type":"string","name":"operation_type"}],"url":"/rest/segment_upload"},"isReference":true,"order":164,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Alternative Method for Segment Upload\"\n}\n[/block]\nFor customers with larger files Beeswax may arrange for the files to be uploaded directly to our cloud instead of using the Buzz API for upload. In this case, you still must POST to the segment_upload method to let us know to \"pick up\" your files and process them.\n\nTo do this, you provide this method with the segment_file_list parameter, which contains a list of files uploaded. You should *not* include the file_name or size_in_bytes parameters.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[host]/rest/segment_upload\\\" -b cookies.txt -d '{\\\"segment_file_list\\\":[\\\"\\\\path\\\\to\\\\file\\\\user_data_sample.txt\\\",\\\"\\\\path\\\\to\\\\file\\\\user_data_sample2.txt\\\"],\\\"account_id\\\":1,\\\"file_format\\\":\\\"DELIMITED\\\",\\\"segment_key_type\\\":\\\"DEFAULT\\\",\\\"user_id_type\\\":\\\"IDFA\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overwriting or Deleting User-Segment Combinations\"\n}\n[/block]\nThe operation_type field on segment uploads acts to control how the new information will be applied to existing data. \n\nTo do a full overwrite of a specific user ID you pass REPLACE_ALL_SEGMENTS. For example, if user ID 123 was previously in segments A and B, and you wanted to remove the user from segment B, you would upload a new file with operation_type set to REPLACE_ALL_SEGMENTS and put user ID 123 in segment A only. \n\nIf you want want to remove the specific segments provided in the file the operation_type is REMOVE_SEGMENTS.\n\nIf you want to remove a user ID from all segments (for example for GDPR opt-outs), you can upload a file with operation_type set to REPLACE_ALL_SEGMENTS and leave the segments as null.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[host]/rest/segment_upload\\\" -b cookies.txt -d '{\\\"file_name\\\":\\\"user_data_sample.txt\\\",\\\"size_in_bytes\\\":412, \\\"operation_type\\\": \\\"REPLACE_ALL_SEGMENTS\\\",\\\"file_format\\\":\\\"DELIMITED\\\",\\\"segment_key_type\\\":\\\"ALTERNATIVE\\\",\\\"user_id_type\\\":\\\"IDFA\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"segment_upload","type":"endpoint","title":"segment_upload"}

### Definition

{{ api_url }}{{ page_api_url }}

### Parameters

#### Body Params

file_name:
required
string
The filename to be uploaded, including the extension. <255 chars, no spaces or special characters other than dashes and underscores.
path_to_file:
string
The location of the file on the server. If this field is populated, Buzz assumes the file was already uploaded and will not allow further uploads. If absent, Buzz will auto-fill this when the file is uploaded in a subsequent POST.
size_in_bytes:
required
integer
Size of the file to be uploaded, in bytes.
datacenter:
string
Not currently used.
file_format:
stringDELIMITED
The type of file format expected. Valid formats are stored in the segment_file_format table.
segment_file_list:
array of strings
When uploading multiple files of segment-user associations, a list of these files can be passed in a single POST. This will generally improve performance of the upload as well.
segment_key_type:
stringDEFAULT
Indicates whether the user IDs in the uploaded file should be put into a segment defined by the segment_key or the alternative_id from the segment. Must be set to either DEFAULT or ALTERNATIVE.
continent:
stringNAM
The destination continent data centers to upload the data. Only one continent may be specified per upload. If a segment is required across continents it must be uploaded twice. Options are NAM, EMEA, or APAC.
user_id_type:
required
string
Indicates the type of IDs being imported, as defined in the "segment_user_type" view. Valid types include BEESWAX, CUSTOMER, IDFA, IDFA_MD5, IDFA_SHA1 , AD_ID, AD_ID_MD5, AD_ID_SHA1 , IP_ADDRESS, OTHER_MOBILE_ID
overwrite:
boolean0
DEPRECATED. When set the segments associated with a user will overwrite all other user-segment associations for the given user. Use the operation_type field instead.
operation_type:
What action should be taken on these users. Commonly set to ADD_SEGMENTS or REPLACE_ALL_SEGMENTS
[block:api-header] { "type": "basic", "title": "Alternative Method for Segment Upload" } [/block] For customers with larger files Beeswax may arrange for the files to be uploaded directly to our cloud instead of using the Buzz API for upload. In this case, you still must POST to the segment_upload method to let us know to "pick up" your files and process them. To do this, you provide this method with the segment_file_list parameter, which contains a list of files uploaded. You should *not* include the file_name or size_in_bytes parameters. [block:code] { "codes": [ { "code": "curl -X POST \"[host]/rest/segment_upload\" -b cookies.txt -d '{\"segment_file_list\":[\"\\path\\to\\file\\user_data_sample.txt\",\"\\path\\to\\file\\user_data_sample2.txt\"],\"account_id\":1,\"file_format\":\"DELIMITED\",\"segment_key_type\":\"DEFAULT\",\"user_id_type\":\"IDFA\"}'", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Overwriting or Deleting User-Segment Combinations" } [/block] The operation_type field on segment uploads acts to control how the new information will be applied to existing data. To do a full overwrite of a specific user ID you pass REPLACE_ALL_SEGMENTS. For example, if user ID 123 was previously in segments A and B, and you wanted to remove the user from segment B, you would upload a new file with operation_type set to REPLACE_ALL_SEGMENTS and put user ID 123 in segment A only. If you want want to remove the specific segments provided in the file the operation_type is REMOVE_SEGMENTS. If you want to remove a user ID from all segments (for example for GDPR opt-outs), you can upload a file with operation_type set to REPLACE_ALL_SEGMENTS and leave the segments as null. [block:code] { "codes": [ { "code": "curl -X POST \"[host]/rest/segment_upload\" -b cookies.txt -d '{\"file_name\":\"user_data_sample.txt\",\"size_in_bytes\":412, \"operation_type\": \"REPLACE_ALL_SEGMENTS\",\"file_format\":\"DELIMITED\",\"segment_key_type\":\"ALTERNATIVE\",\"user_id_type\":\"IDFA\"}'", "language": "curl" } ] } [/block]