Importing Contacts using the API

Prerequisites

  1. Create and retrieve API Token under “Developer”, “API Tokens”
    1. Use as basic authorization header, example below
    2. Construct string separated by colon “user:pass” and then base64 encode. See: https://tools.ietf.org/html/rfc7617
  2. Retrieve account key from “Account”, “Settings”, “General” (e.g., “firstbank”)
    1. Use as `X-Account-Key` header

API Documentation

Importing contacts require the following:

  1. Create an `upload`: https://omnigage.docs.apiary.io/#reference/media-resources/upload/create-an-upload
    1. The `upload` instance returns a pre-signed S3 URL to be used for uploading the CSV or XLS.
    2. Note: Retrieve the `upload` instance ID to be used when creating the import.
  2. Create the import: https://omnigage.docs.apiary.io/#reference/import-resources/import-contact-collection/create-import-contact

Example Requests

1. Create Upload

Generates a pre-signed URL to upload to S3. The upload instance ID (see `data.id` below) will be used when creating the import.

Request 
POST /api/v1/uploads
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z
{
   "name":"import-5.xlsx",
   "type":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
   "size":37482
}
Response 
Content-Type: application/json
{
   "data":{
      "type":"uploads",
      "id":"Q843fc2UoJf4B5CrQxQ6Cd",
      "attributes":{
         "expires-at":"Fri, 28 Feb 2020 21:27:24 GMT",
         "max-length-in-bytes":5368724480,
         "request-url":"https://omnigage-example.s3-us-west-1.amazonaws.com/",
         "request-method":"post",
         "request-headers":[
            {
               "x-amz-server-side-encryption":"AES256"
            }
         ],
         "request-form-data":[
            {
               "acl":"private"
            },
            {
               "AWSAccessKeyId":"AKIASCCH57"
            },
            {
               "key":"uploads/28636c96bd134863ba83450d56c/${filename}"
            },
            {
               "policy":"eyJleHBpcmF0aifSwgeyJidWNrZXQiOiAib21uaWdhZ2UtcHJvZHVjdGlvbi1tZWRpYSJ9LCBbInN0YXJ0cy13aXRoIiwgIiRrZXkiLCAidXBsb2Fkcy8yODYzNmM5NmJkMTM0ODYzYjJkOTQzYTgzNDUwZDU2Yy8iXSwgWyJzdGFydHMtd2lQ4MF1dfQ=="
            },
            {
               "signature":"XZHFYrd/AjmsGnUS1Bg="
            }
         ]
      }
   }
}

2. Upload to S3

Use the upload response to upload directly to S3.

Request 
POST /
Host: omnigage-example.s3-us-west-1.amazonaws.com
Accept: */*
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.9
Connection: keep-alive
Content-Length: 38825
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryHA24Z2hmBNFyzQmA

x-amz-server-side-encryption: AES256

------WebKitFormBoundaryHA24Z2hmBNFyzQmA
Content-Disposition: form-data; name="acl"

private
------WebKitFormBoundaryHA24Z2hmBNFyzQmA
Content-Disposition: form-data; name="AWSAccessKeyId"

AKIAJKIAISCCH57CAUEQ
------WebKitFormBoundaryHA24Z2hmBNFyzQmA
Content-Disposition: form-data; name="key"

uploads/28636c96bd134863b2d943a83450d56c/${filename}
------WebKitFormBoundaryHA24Z2hmBNFyzQmA
Content-Disposition: form-data; name="policy"

eyJleHBpcmF0aW9uIjogIjIwMjAtMDItMjLCBbImNvbnRlbnQtbGVuZ3RoLXJhbmdlIiwgMCwgNTM2ODcyNDQ4MF1dfQ==
------WebKitFormBoundaryHA24Z2hmBNFyzQmA
Content-Disposition: form-data; name="signature"

XXK0JQZHFYrd/AjmsGnuTyUS1Bg=
------WebKitFormBoundaryHA24Z2hmBNFyzQmA
Content-Disposition: form-data; name="Content-Type"

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
------WebKitFormBoundaryHA24Z2hmBNFyzQmA
Content-Disposition: form-data; name="file"; filename="import-5.xlsx"
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

------WebKitFormBoundaryHA24Z2hmBNFyzQmA--
Response 
Access-Control-Allow-Methods: GET, POST, HEAD
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 3000
Date: Fri, 28 Feb 2020 20:27:26 GMT
ETag: "fbf34faef3f8a54e4"
Location: https://omnigage-example.s3-us-west-1.amazonaws.com/uploads%2F28636c96bd134863b2d943a83450d56c%2Fimport-5.xlsx
Server: AmazonS3
Vary: Origin, Access-Control-Request-Headers, Access-Control-Request-Method
x-amz-id-2: LRzGobdz7WkiIdHZ8zlzlBKgf+Upwi90M0P5de9eBsWBw=
x-amz-request-id: 307857C5
x-amz-server-side-encryption: AES256
x-amz-version-id: r4ZXTFc99G.LI81mV6

3. Create Import

Request 
POST /api/v1/import-contacts
Host: api.omnigage.io
X-Account-Key: firstbank
Authorization: Basic SDcyTFk0clFIU1hUYUIzR2Z
{
   "data":{
      "attributes":{
         "status":"queued",
         "unique-primary-phone":true
      },
      "relationships":{
         "upload":{
            "data":{
               "type":"uploads",
               "id":"Q843fc2UoJf4B5CrQxQ6Cd"
            }
         }
      },
      "type":"import-contacts"
   }
}
Response 
{
   "data":{
      "type":"import-contacts",
      "id":"rgpAPfNsdJf2Rkcwv2gVEM",
      "attributes":{
         "status":"queued",
         "unique-primary-email":false,
         "unique-primary-phone":true,
         "update-pruning":false,
         "enable-preflights":false,
         "header":[
            "First Name",
            "Last Name",
            "Company",
            "Phone Number",
            "Email Address"
         ],
         "mapping":[
            "first-name",
            "last-name",
            "company",
            "phone1-phone-number",
            "email1-email-address"
         ],
         "sample":[
            "Sampson",
            "Victor",
            "Omnigage",
            "14076341732",
            "sampson.victor@mailinator.com"
         ],
         "count-created":0,
         "count-updated":0,
         "count-erred":0,
         "count-total":0,
         "count-resolved":0,
         "count-skipped":0,
         "created-at":"2020-02-28T20:44:47.940610+00:00",
         "updated-at":"2020-02-28T20:44:47.940616+00:00"
      },
      "relationships":{
         "created-by":{
            "data":{
               "type":"memberships",
               "id":"FJ653kkb36jbqBUNPx9sqJ"
            }
         },
         "updated-by":{
            "data":{
               "type":"memberships",
               "id":"FJ653kkb36jbqBUNPx9sqJ"
            }
         },
         "list":{
            "data":null
         },
         "results":{
            "links":{
               "related":"https://testing.omnigage.io/api/v1/import-contacts/rgpAPfNsdJf2Rkcwv2gVEM/results"
            }
         },
         "original-file":{
            "data":{
               "type":"files",
               "id":"mAC86Wxd4JnhgKxjydEbed"
            }
         },
         "errors-file":{
            "data":null
         }
      }
   }
}

Still need help? Contact Us Contact Us