Assign or update a keyword in MobileConnect using the REST API

1)  Finding the keyword using the /contacts/v1/attributeSets/name:MobileConnect%20Subscriptions route

Use the below route to return all possible values for all fields within MobileConnect Subscriptions.

Note: There are only 50 results returned per page. The keyword ID returned is in GUID form. In order to match that to a keyword, such as JOIN, you will need to create a test record in your account to see which keyword value is paired with the ID.

GET /contacts/v1/attributeSets/name:MobileConnect%20Subscriptions

Below is an example of the REST API call response. You can look up item with matching Mobile Number "value" to find the associated Keyword "value". For the following example, Keyword for Mobile Name 13175555555 is 04689a0c-c3c6-4814-b5bb-454342189c50. 
 

{
  "id": "5d77110e-c957-e911-80dd-1402ec74dd4c",
  "key": "MobileConnect Subscriptions",
  "customerKey": "MobileSubscriptions",
  "name": "MobileConnect Subscriptions",
  "page": 1,
  "pageSize": 50,
  "count": 1,
  "items": [
    {
      "values": [
        {
          "id": "6277110e-c957-e911-80dd-1402ec74dd4c",
          "key": "MobileConnect Subscriptions.Modified Date",
          "name": "Modified Date",
          "value": "5/10/2019 7:35:06 AM"
        },
        {
          "id": "6077110e-c957-e911-80dd-1402ec74dd4c",
          "key": "MobileConnect Subscriptions.Mobile Number",
          "name": "Mobile Number",
          "value": "13175555555"
        },
        {
          "id": "6677110e-c957-e911-80dd-1402ec74dd4c",
          "key": "MobileConnect Subscriptions.Opt Out Date",
          "name": "Opt Out Date"
        },
        {
          "id": "6477110e-c957-e911-80dd-1402ec74dd4c",
          "key": "MobileConnect Subscriptions.Opt In Method",
          "name": "Opt In Method",
          "value": "4"
        },
        {
          "id": "6a77110e-c957-e911-80dd-1402ec74dd4c",
          "key": "MobileConnect Subscriptions.Source Object ID",
          "name": "Source Object ID",
          "value": "F8B5F0AB-1C68-4048-BF63-B4593AED65B7"
        },
        {
          "id": "6877110e-c957-e911-80dd-1402ec74dd4c",
          "key": "MobileConnect Subscriptions.Opt Out Status",
          "name": "Opt Out Status",
          "value": "0"
        },
        {
          "id": "6377110e-c957-e911-80dd-1402ec74dd4c",
          "key": "MobileConnect Subscriptions.Opt In Date",
          "name": "Opt In Date",
          "value": "5/10/2019 7:35:06 AM"
        },
        {
          "id": "6777110e-c957-e911-80dd-1402ec74dd4c",
          "key": "MobileConnect Subscriptions.Opt Out Method",
          "name": "Opt Out Method"
        },
        {
          "id": "6577110e-c957-e911-80dd-1402ec74dd4c",
          "key": "MobileConnect Subscriptions.Opt In Status",
          "name": "Opt In Status",
          "value": "2"
        },
        {
          "id": "6b77110e-c957-e911-80dd-1402ec74dd4c",
          "key": "MobileConnect Subscriptions.Keyword",
          "name": "Keyword",
          "value": "04689a0c-c3c6-4814-b5bb-454342189c50"
        },
        {
          "id": "6977110e-c957-e911-80dd-1402ec74dd4c",
          "key": "MobileConnect Subscriptions.Source",
          "name": "Source",
          "value": "4"
        },
        {
          "id": "5f77110e-c957-e911-80dd-1402ec74dd4c",
          "key": "MobileConnect Subscriptions.Created Date",
          "name": "Created Date",
          "value": "5/10/2019 7:35:06 AM"
        }
      ]
    }
  ],
  "links": {},
  "requestServiceMessageID": "be1eaa82-ec17-46a6-87db-5f0e9a621ae9",
  "responseDateTime": "2020-04-08T07:26:54.7181035-06:00",
  "resultMessages": [],
  "serviceMessageID": "444329ed-95bc-4ada-bfdd-317fd22d7039"
}

If the response returned more than 50 records (more than 1 page), you will need to use GET /contacts/v1/attributeSets/{id}?$page=2&$pageSize=50 to query additional pages. Example below.
 
GET /contacts/v1/attributeSets/5d77110e-c957-e911-80dd-1402ec74dd4c?$page=2&$pageSize=50

2.) Finding the keyword using the _SMSSubscriptionlog data view

select  SubscriptionDefinitionID from _SMSSubscriptionLog 
where MobileNumber = '13175555555'

Once you are sure of the ID value, you can create a contact using the /contacts/v1/contacts route. Below is an example call. Using a POST method it will create the record. Using a PATCH method it will update an existing record. 

{
    "contactKey": "KeyWordTest",
    "attributeSets": [
        {
            "name": "MobileConnect Demographics",
            "items": [
                {
                    "values": [
                        {
                            "name": "Mobile Number",
                            "value": "13175555555"
                        },
                        {
                            "name": "Locale",
                            "value": "US"
                        },
                        {
                            "name": "Status",
                            "value": 1
                        }
                    ]
                }
            ]
        },
        {
            "name": "MobileConnect Subscriptions",
            "items": [
                {
                    "values": [
                        {
                            "name": "Keyword",
                            "value": "9FAC7957-0CB5-41C2-98AA-88937FCDCFD1"
                        },
                        {
                            "name": "Opt In Status",
                            "value": "2"
                        },
                        {
                            "name": "Opt Out Status",
                            "value": 0
                        },
                        {
                            "name": "Mobile Number",
                            "value": "13175555555"
                        }
                    ]
                }
            ]
        }
    ]
}