Create a dataflow for Mailchimp Members using the Flow Service API
The following tutorial walks you through the steps to create a source connection and a dataflow to bring Mailchimp Members data to Platform using the Flow Service API.
Prerequisites
Before you can connect Mailchimp to Adobe Experience Platform using OAuth 2 refresh code, you must first retrieve your access token for MailChimp. See the Mailchimp OAuth 2 guide for detailed instructions on finding your access token.
Create a base connection base-connection
Once you have retrieved your Mailchimp authentication credentials, you can now start the process of creating dataflow to bring Mailchimp Members data to Platform. The first step in creating a dataflow is to create a base connection.
A base connection retains information between your source and Platform, including your source’s authentication credentials, the current state of the connection, and your unique base connection ID. The base connection ID allows you to explore and navigate files from within your source and identify the specific items that you want to ingest, including information regarding their data types and formats.
Mailchimp supports both basic authentication and OAuth 2 refresh code. See the following examples for guidance on how to authenticate with either authentication types.
Create a Mailchimp base connection using basic authentication
To create a Mailchimp base connection using basic authentication, make a POST request to the /connections
endpoint of Flow Service API while providing credentials for your authorizationTestUrl
, username
, and password
.
API format
POST /connections
Request
The following request creates a base connection for Mailchimp:
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"name": "Mailchimp base connection with basic authentication",
"description": "Mailchimp Members base connection with basic authentication",
"connectionSpec": {
"id": "2e8580db-6489-4726-96de-e33f5f60295f",
"version": "1.0"
},
"auth": {
"specName": "Basic Authentication",
"params": {
"authorizationTestUrl": "https://login.mailchimp.com/oauth2/metadata",
"username": "{USERNAME}",
"password": "{PASSWORD}"
}
}
}'
name
description
connectionSpec.id
auth.specName
auth.params.authorizationTestUrl
auth.params.username
auth.params.password
Response
A successful response returns the newly created base connection, including its unique connection identifier (id
). This ID is required to explore your source’s file structure and contents in the next step.
{
"id": "4cea039f-f1cc-4fa5-9136-db8dd4c7fbfa",
"etag": "\"4000cff7-0000-0200-0000-6154bad60000\""
}
Create a Mailchimp base connection using OAuth 2 refresh code
To create a Mailchimp base connection using OAuth 2 refresh code, make a POST request to the /connections
endpoint while providing credentials for your authorizationTestUrl
, and accessToken
.
API format
POST /connections
Request
The following request creates a base connection for Mailchimp:
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"name": "MailChimp base connection with OAuth 2 refresh code",
"description": "MailChimp Members base connection with OAuth 2 refresh code",
"connectionSpec": {
"id": "2e8580db-6489-4726-96de-e33f5f60295f",
"version": "1.0"
},
"auth": {
"specName": "oAuth2RefreshCode",
"params": {
"authorizationTestUrl": "https://login.mailchimp.com/oauth2/metadata",
"accessToken": "{ACCESS_TOKEN}"
}
}
}'
name
description
connectionSpec.id
auth.specName
auth.params.authorizationTestUrl
auth.params.accessToken
Response
A successful response returns the newly created base connection, including its unique connection identifier (id
). This ID is required to explore your source’s file structure and contents in the next step.
{
"id": "4cea039f-f1cc-4fa5-9136-db8dd4c7fbfa",
"etag": "\"4000cff7-0000-0200-0000-6154bad60000\""
}
Explore your source explore
Using the base connection ID you generated in the previous step, you can explore files and directories by performing GET requests.
{SOURCE_PARAMS}
, you must encode the entire list_id
string in base64. For example, "list_id": "10c097ca71"
encoded in base64 equates to eyJsaXN0SWQiOiIxMGMwOTdjYTcxIn0=
.API format
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}
When performing GET requests to explore your source’s file structure and contents, you must include the query parameters that are listed in the table below:
{BASE_CONNECTION_ID}
{OBJECT_TYPE}
rest
.{OBJECT}
{FILE_TYPE}
{PREVIEW}
{SOURCE_PARAMS}
list_id
.Request
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connections/05c595e5-edc3-45c8-90bb-fcf556b57c4b/explore?objectType=rest&object=json&fileType=json&preview=true&sourceParams=eyJsaXN0SWQiOiIxMGMwOTdjYTcxIn0=' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns the structure of the queried file.
{
"data": [
{
"list_id": "10c097ca71",
"_links": [
{
"rel": "self",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/CollectionResponse.json",
"schema": "https://us6.api.mailchimp.com/schema/3.0/Paths/Lists/Members/Collection.json"
},
{
"rel": "parent",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json"
},
{
"rel": "create",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
"method": "POST",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json",
"schema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/POST.json"
}
],
"members": [
{
"id": "cff65fb4c5f5828666ad846443720efd",
"email_address": "kendallt2134@gmail.com",
"unique_email_id": "72c758cbf1",
"contact_id": "874a0d6e9ddb89d8b4a31e416ead2d6f",
"full_name": "Kendall Roy",
"web_id": 547094062,
"email_type": "html",
"status": "subscribed",
"consents_to_one_to_one_messaging": true,
"merge_fields": {
"FNAME": "Kendall",
"LNAME": "Roy",
"ADDRESS": {
"country": "US"
}
},
"stats": {
"avg_open_rate": 0,
"avg_click_rate": 0
},
"ip_opt": "103.43.112.97",
"timestamp_opt": "2021-06-01T15:31:36+00:00",
"member_rating": 2,
"last_changed": "2021-06-01T15:31:36+00:00",
"vip": false,
"location": {
"latitude": 0,
"longitude": 0,
"gmtoff": 0,
"dstoff": 0
},
"source": "Admin Add",
"tags_count": 0,
"list_id": "10c097ca71",
"_links": [
{
"rel": "self",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/cff65fb4c5f5828666ad846443720efd",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json"
},
{
"rel": "parent",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/CollectionResponse.json",
"schema": "https://us6.api.mailchimp.com/schema/3.0/Paths/Lists/Members/Collection.json"
},
{
"rel": "update",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/cff65fb4c5f5828666ad846443720efd",
"method": "PATCH",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json",
"schema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/PATCH.json"
},
{
"rel": "upsert",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/cff65fb4c5f5828666ad846443720efd",
"method": "PUT",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json",
"schema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/PUT.json"
},
{
"rel": "delete",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/cff65fb4c5f5828666ad846443720efd",
"method": "DELETE"
},
{
"rel": "activity",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/cff65fb4c5f5828666ad846443720efd/activity",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Activity/Response.json"
},
{
"rel": "goals",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/cff65fb4c5f5828666ad846443720efd/goals",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Goals/Response.json"
},
{
"rel": "notes",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/cff65fb4c5f5828666ad846443720efd/notes",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Notes/CollectionResponse.json"
},
{
"rel": "events",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/cff65fb4c5f5828666ad846443720efd/events",
"method": "POST",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Events/POST.json"
},
{
"rel": "delete_permanent",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/cff65fb4c5f5828666ad846443720efd/actions/delete-permanent",
"method": "POST"
}
]
}
]
}
]
}
Create a source connection source-connection
You can create a source connection by making a POST request to the Flow Service API. A source connection consists of a connection ID, a path to the source data file, and a connection spec ID.
To create a source connection, you must also define an enum value for the data format attribute.
Use the following the enum values for file-based sources:
delimited
json
parquet
For all table-based sources, set the value to tabular
.
API format
POST /sourceConnections
Request
The following request creates a source connection for Mailchimp:
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"name": "MailChimp source connection to ingest listId",
"description": "MailChimp Members source connection to ingest listId",
"baseConnectionId": "4cea039f-f1cc-4fa5-9136-db8dd4c7fbfa",
"connectionSpec": {
"id": "2e8580db-6489-4726-96de-e33f5f60295f",
"version": "1.0"
},
"data": {
"format": "json",
},
"params": {
"listId": "10c097ca71"
}
}'
name
description
baseConnectionId
connectionSpec.id
data.format
params.listId
Response
A successful response returns the unique identifier (id
) of the newly created source connection. This ID is required in a later step to create a dataflow.
{
"id": "a51e4cf6-65ef-45f4-b4bf-4f03da5f01cc",
"etag": "\"6b02b65d-0000-0200-0000-6154bfbe0000\""
}
Create a target XDM schema target-schema
In order for the source data to be used in Platform, a target schema must be created to structure the source data according to your needs. The target schema is then used to create a Platform dataset in which the source data is contained.
A target XDM schema can be created by performing a POST request to the Schema Registry API.
For detailed steps on how to create a target XDM schema, see the tutorial on creating a schema using the API.
Create a target dataset target-dataset
A target dataset can be created by performing a POST request to the Catalog Service API, providing the ID of the target schema within the payload.
For detailed steps on how to create a target dataset, see the tutorial on creating a dataset using the API.
Create a target connection target-connection
A target connection represents the connection to the destination where the ingested data lands in. To create a target connection, you must provide the fixed connection specification ID that corresponds to the Data Lake. This ID is: c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
You now have the unique identifiers a target schema a target dataset and the connection spec ID to the Data Lake. Using these identifiers, you can create a target connection using the Flow Service API to specify the dataset that will contain the inbound source data.
API format
POST /targetConnections
Request
The following request creates a target connection for Mailchimp:
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"name": "MailChimp target connection",
"description": "MailChimp Members target connection",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "parquet_xdm",
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/570630b91eb9d5cf5db0436756abb110d02912917a67da2d",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "6155e3a9bd13651949515f14"
}
}'
name
description
connectionSpec.id
c604ff05-7f1a-43c0-8e18-33bf874cb11c
.data.format
params.dataSetId
Response
A successful response returns the new target connection’s unique identifier (id
). This ID is required in later steps.
{
"id": "8db5fb4a-6ce8-4370-afc0-1765e39535a5",
"etag": "\"960093ce-0000-0200-0000-6154da3e0000\""
}
Create a mapping mapping
In order for the source data to be ingested into a target dataset, it must first be mapped to the target schema that the target dataset adheres to. This is achieved by performing a POST request to the Data Prep API with data mappings defined within the request payload.
API format
POST /conversion/mappingSets
Request
curl -X POST \
'https://platform.adobe.io/data/foundation/conversion/mappingSets' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"version": 0,
"xdmSchema": "_{TENANT_ID}.schemas.570630b91eb9d5cf5db0436756abb110d02912917a67da2d",
"xdmVersion": "1.0",
"mappings": [
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "merge_fields.FNAME",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "merge_fields.LNAME",
"identity": false,
"version": 0
}
]
}'
xdmSchema
mappings.destinationXdmPath
mappings.sourceAttribute
mappings.identity
Response
A successful response returns details of the newly created mapping including its unique identifier (id
). This value is required in a later step to create a dataflow.
{
"id": "5a365b23962d4653b9d9be25832ee5b4",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Create a flow flow
The last step towards bringing Mailchimp data to Platform is to create a dataflow. By now, you have the following required values prepared:
A dataflow is responsible for scheduling and collecting data from a source. You can create a dataflow by performing a POST request while providing the previously mentioned values within the payload.
To schedule an ingestion, you must first set the start time value to epoch time in seconds. Then, you must set the frequency value to one of the five options: once
, minute
, hour
, day
, or week
. The interval value designates the period between two consecutive ingestions and creating a one-time ingestion does not require an interval to be set. For all other frequencies, the interval value must be set to equal or greater than 15
.
API format
POST /flows
Request
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"name": "MailChimp Members dataflow",
"description": "MailChimp Members dataflow",
"flowSpec": {
"id": "6499120c-0b15-42dc-936e-847ea3c24d72",
"version": "1.0"
},
"sourceConnectionIds": [
"a51e4cf6-65ef-45f4-b4bf-4f03da5f01cc"
],
"targetConnectionIds": [
"8db5fb4a-6ce8-4370-afc0-1765e39535a5"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "5a365b23962d4653b9d9be25832ee5b4",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1632809759",
"frequency": "minute",
"interval": 15
}
}'
name
description
flowSpec.id
6499120c-0b15-42dc-936e-847ea3c24d72
.flowSpec.version
1.0
.sourceConnectionIds
targetConnectionIds
transformations
transformations.name
transformations.params.mappingId
transformations.params.mappingVersion
0
.scheduleParams.startTime
scheduleParams.frequency
once
, minute
, hour
, day
, or week
.scheduleParams.interval
once
and should be greater than or equal to 15
for other frequency values.Response
A successful response returns the ID (id
) of the newly created dataflow. You can use this ID to monitor, update, or delete your dataflow.
{
"id": "209812ad-7bef-430c-b5b2-a648aae72094",
"etag": "\"2e01f11d-0000-0200-0000-615649660000\""
}
Appendix
The following section provides information on the steps you can to monitor, update, and delete your dataflow.
Monitor your dataflow
Once your dataflow has been created, you can monitor the data that is being ingested through it to see information on flow runs, completion status, and errors. For complete API examples, read the guide on monitoring your sources dataflows using the API.
Update your dataflow
Update the details of your dataflow, such as its name and description, as well as its run schedule and associated mapping sets by making a PATCH request to the /flows
endpoint of Flow Service API, while providing the ID of your dataflow. When making a PATCH request, you must provide your dataflow’s unique etag
in the If-Match
header. For complete API examples, read the guide on updating sources dataflows using the API.
Update your account
Update the name, description, and credentials of your source account by performing a PATCH request to the Flow Service API while providing your base connection ID as a query parameter. When making a PATCH request, you must provide your source account’s unique etag
in the If-Match
header. For complete API examples, read the guide on updating your source account using the API.
Delete your dataflow
Delete your dataflow by performing a DELETE request to the Flow Service API while providing the ID of the dataflow you want to delete as part of the query parameter. For complete API examples, read the guide on deleting your dataflows using the API.
Delete your account
Delete your account by performing a DELETE request to the Flow Service API while providing the base connection ID of the account you want to delete. For complete API examples, read the guide on deleting your source account using the API.