External Segments

In its simplest definition, a segment refers to a list of user IDs. Other components within the system can utilize or consume this segment. NeoDay can ingest external data in the form of a CSV file containing user IDs of a connected OpenID provider. This data undergoes processing in NeoDay, where it cross-checks for matching users, if any, and generates a segment. The resulting segment can then be used within the Neoday system.

External Segment States

pending - this state is set when an external segment is imported into the system, indicating an initial pending status for the segment.

processing - this state signifies that the NeoDay system is actively cross-checking matching IDs for the segment.

processed - this state indicates the completion of cross-checking, with the resulting segment now available for retrieval.

Import External Data

Importing external data initially requires the following in the payload: title, identifier, and the file.

POST /api/1/external-segmentation/external-segment?locale=en_GB HTTP/1.1
Host: gateway.acme.neo.day
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9........
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary6cBVMqw6HF0kPOJS

------WebKitFormBoundary6cBVMqw6HF0kPOJS
Content-Disposition: form-data; name="title"

People who loves to watch horror films
------WebKitFormBoundary6cBVMqw6HF0kPOJS
Content-Disposition: form-data; name="identifier"

sso
------WebKitFormBoundary6cBVMqw6HF0kPOJS
Content-Disposition: form-data; name="file"; filename="externalData.csv"
Content-Type: text/csv


------WebKitFormBoundary6cBVMqw6HF0kPOJS--

HTTP/1.1 200 OK
Content-Type: application/json

multipart/form-data: This indicates that the request body is structured as a series of parts, each containing a set of key-value pairs. This is commonly used for file uploads.

boundary=----WebKitFormBoundary6cBVMqw6HF0kPOJS: This specifies the boundary string that will be used to separate the different parts of the request. In this case, the boundary is set to ----WebKitFormBoundary6cBVMqw6HF0kPOJS. The boundary string should be unique and not present in the actual data.

It should be noted that the csv file containing the identifier (sso) should be in one column with no header. Such that it looks like this:

ssoIdentifer1
ssoIdentifer2
ssoIdentifer3
ssoIdentifer4

Fetching list of external segments

Uploaded external data can be retrieved using the endpoint below: For example:

GET /api/1/external-segmentation/external-segment/list HTTP/1.1
Host: gateway.acme.neo.day
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9........
Content-Type: application/json

[
    
    {
        "id": "vw0jx0lotknppq9plci67hvbf",
        "name": "People who love to watch Martin scorsese's film",
        "identifier": "sso",
        "state": "processed",
        "externalUserCount": 100000,
        "internalUserCount": 4,
        "documentID": "cs8fon5q38iwxlz6i674d4kk8",
        "fileName": "100k.csv",
        "updated": "2024-01-17T11:48:58+00:00"
    },
    {
        "id": "ppltl899cufw53k0ues8monln",
        "name": "People who love to watch horror films",
        "identifier": "sso",
        "state": "processed",
        "externalUserCount": 100,
        "internalUserCount": 0,
        "documentID": "hqhmj3ae4bmj7ltfhnfpkhkuf",
        "fileName": "externalData.csv",
        "updated": "2024-01-18T03:23:14+00:00"
    }
]

Fetching individual of external segment

GET /api/1/external-segmentation/external-segment/ppltl899cufw53k0ues8monln HTTP/1.1
Host: gateway.acme.neo.day
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9........
Content-Type: application/json

{
    "id": "ppltl899cufw53k0ues8monln",
    "name": "People who love to watch horror films",
    "identifier": "sso",
    "state": "processed",
    "externalUserCount": 100,
    "internalUserCount": 0,
    "documentID": "hqhmj3ae4bmj7ltfhnfpkhkuf",
    "fileName": "externalData.csv",
    "updated": "2024-01-18T03:23:14+00:00"
}

Updating an external segment

If you desire to update the external segment, you can upload a new file, following a process similar to creating a new external segment, with the exception that you attach the ID in the payload.

POST api/1/external-segmentation/external-segment/ppltl899cufw53k0ues8monln?locale=en_GB HTTP/1.1
Host: gateway.internal.neo.day
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9........
Content-Type: application/json

------WebKitFormBoundaryMYPT1txw13wC8k7B
Content-Disposition: form-data; name="title"

People who love romance films
------WebKitFormBoundaryMYPT1txw13wC8k7B
Content-Disposition: form-data; name="identifier"

sso
------WebKitFormBoundaryMYPT1txw13wC8k7B
Content-Disposition: form-data; name="file"; filename="newfile.csv"
Content-Type: text/csv


------WebKitFormBoundaryMYPT1txw13wC8k7B
Content-Disposition: form-data; name="id"

vhw7duf6qt2g8xpcb4spazd6e
------WebKitFormBoundaryMYPT1txw13wC8k7B--

HTTP/1.1 200 OK
Content-Type: application/json

Deleting an external segment

An external segment can only be deleted when its state is processed and if it is not being used as a condition in the segmentation component.

DELETE /api/1/external-segmentation/external-segment/ppltl899cufw53k0ues8monln?locale=en_GB HTTP/1.1
Host: gateway.acme.neo.day
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9........
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json