Difference between revisions of "Adding or Updating Members"

From Enterprise Help
Jump to: navigation, search
Line 24: Line 24:
 
   {  
 
   {  
 
  "odata.metadata":"[http://enterprise.qa.fishbowl.com/API/odata/v1/2147483947/ http://services.fishbowl.com/API/odata/v1/2147483947/]
 
  "odata.metadata":"[http://enterprise.qa.fishbowl.com/API/odata/v1/2147483947/ http://services.fishbowl.com/API/odata/v1/2147483947/]
                $metadata#Members",
+
        $metadata#Members",
 
  "value":[  
 
  "value":[  
  {  
+
{  
    "MemberID":"2148166490",
+
"MemberID":"2148166490",
    "SiteID":"2147483947",
+
"SiteID":"2147483947",
    "EmailAddress":"johndoe@test.com",
+
"EmailAddress":"johndoe@test.com",
    "HardBounces":0,
+
"HardBounces":0,
    "SoftBounces":0,
+
"SoftBounces":0,
    "Suppressed":false,
+
"Suppressed":false,
    "IsTester":false,
+
"IsTester":false,
    "CreatedUtc":"2014-11-07T17:13:23.88Z",
+
"CreatedUtc":"2014-11-07T17:13:23.88Z",
    "LastUpdatedUtc":"0001-01-01T05:00:00Z",
+
"LastUpdatedUtc":"0001-01-01T05:00:00Z",
    "StringFields":[  
+
"StringFields":[  
        {  
+
{  
          "Name":"FirstName",
+
  "Name":"FirstName",
          "Value":"John"  
+
  "Value":"John"  
        },
+
},
        {  
+
{  
          "Name":"LastName",
+
  "Name":"LastName",
          "Value":"Doe"  
+
  "Value":"Doe"  
        },
+
},
        {
+
{
          "Name":"StoreCode",
+
  "Name":"StoreCode",
          "Value":"001"  
+
  "Value":"001"  
        },
+
},
        {
+
{
          "Name":"InputSource",
+
  "Name":"InputSource",
          "Value":"Partner"  
+
  "Value":"Partner"  
        }
+
}
    ],
+
],
    "BooleanFields":[],
+
"BooleanFields":[],
    "Int32Fields":[],
+
"Int32Fields":[],
    "Int64Fields":[],
+
"Int64Fields":[],
    "DateFields":[  
+
"DateFields":[  
        {  
+
{  
          "Name":"Birthdate",
+
  "Name":"Birthdate",
          "Value":"1999-04-03T00:00:00"  
+
  "Value":"1999-04-03T00:00:00"  
        },
+
},
        {  
+
{  
          "Name":"Anniversary",
+
  "Name":"Anniversary",
          "Value":null  
+
  "Value":null  
        },
+
},
        {  
+
{  
          "Name":"JoinDate",
+
  "Name":"JoinDate",
          "Value":"2014-12-04T00:00:00.000"  
+
  "Value":"2014-12-04T00:00:00.000"  
        }
+
}
    ],
+
],
    "DecimalFields":[],
+
"DecimalFields":[],
    "Subscriptions":[  
+
"Subscriptions":[  
        {
+
{
          "ListID":"2147484225",
+
  "ListID":"2147484225",
          "IsSubscribed":true
+
  "IsSubscribed":true
        },
+
},
        {
+
{
          "ListID":"2147485177",
+
  "ListID":"2147485177",
          "IsSubscribed":true
+
  "IsSubscribed":true
        }
+
}
    ],
+
],
    "MemberTags":[]  
+
"MemberTags":[]  
  }  
+
}  
 
  ]  
 
  ]  
 
  }
 
  }
Line 105: Line 105:
 
  "EmailAddress":"johndoe@test.com",
 
  "EmailAddress":"johndoe@test.com",
 
  "SubscriptionsForMember":[
 
  "SubscriptionsForMember":[
  {
+
{
    "ListID":"1122334455",
+
"ListID":"1122334455",
    "IsSubscribed":true
+
"IsSubscribed":true
  }
+
}
 
  ],
 
  ],
 
  "StringFields":[
 
  "StringFields":[
  {
+
{
    "Name":"FirstName",
+
"Name":"FirstName",
    "Value":"John"
+
"Value":"John"
  },
+
},
  {
+
{
    "Name":"LastName",
+
"Name":"LastName",
    "Value":"Doe"
+
"Value":"Doe"
  },
+
},
  {
+
{
    "Name":"StoreCode",
+
"Name":"StoreCode",
    "Value":"001"
+
"Value":"001"
  },
+
},
  {
+
{
    "Name":"InputSource",
+
"Name":"InputSource",
    "Value":"Partner"
+
"Value":"Partner"
  }
+
}
 
  ],
 
  ],
 
  "DateFields":[
 
  "DateFields":[
  {
+
{
    "Name":"Birthdate",
+
"Name":"Birthdate",
    "Value":"1999-04-03T00:00:00"
+
"Value":"1999-04-03T00:00:00"
  },
+
},
  {
+
{
    "Name":"Anniversary",
+
"Name":"Anniversary",
    "Value":null
+
"Value":null
  },
+
},
  {
+
{
    "Name":"JoinDate",
+
"Name":"JoinDate",
    "Value":"2014-12-04T00:00:00"
+
"Value":"2014-12-04T00:00:00"
  }
+
}
 
  ]
 
  ]
 
  }
 
  }
Line 168: Line 168:
 
  "EmailAddress":"johndoe@test.com",
 
  "EmailAddress":"johndoe@test.com",
 
  "SubscriptionsForMember":[
 
  "SubscriptionsForMember":[
  {
+
{
    "ListID":"1122334455",
+
"ListID":"1122334455",
    "IsSubscribed":true         
+
"IsSubscribed":true         
  }
+
}
 
  ],
 
  ],
 
  "StringFields":[
 
  "StringFields":[
  {
+
{
    "Name":"FirstName",
+
"Name":"FirstName",
    "Value":"John"
+
"Value":"John"
  },
+
},
  {
+
{
    "Name":"LastName",
+
"Name":"LastName",
    "Value":"Doe"
+
"Value":"Doe"
  },
+
},
  {
+
{
    "Name":"StoreCode",
+
"Name":"StoreCode",
    "Value":"001"
+
"Value":"001"
  }
+
}
 
  ],
 
  ],
 
  "DateFields":[
 
  "DateFields":[
  {
+
{
    "Name":"Birthdate",
+
"Name":"Birthdate",
    "Value":"1999-04-03T00:00:00"
+
"Value":"1999-04-03T00:00:00"
  },
+
},
  {
+
{
    "Name":"Anniversary",
+
"Name":"Anniversary",
    "Value":"2009-02-14T00:00:00"
+
"Value":"2009-02-14T00:00:00"
  }
+
}
 
  ]
 
  ]
 
  }
 
  }
 +
 +
== '''Dates & Date Conversion''' ==
 +
 +
Dates are stored on Fishbowl database using US Eastern Timezone.  However, the Enterprise REST API will convert datetime values to UTC. 
 +
 +
 If a Get request is issued for an existing member whose JoinDate value is 2/14/2020 12 AM in the database, the JSON returned by the API will be:
 +
<div style="background:#eee;border:1px solid #ccc;padding:5px 10px;"><pre>"DateFields": [
 +
 +
        {
 +
 +
          "Name": "JoinDate",
 +
 +
          "Value": "2020-02-14T05:00:00Z"
 +
 +
        }]</pre>
 +
</div>
 +
To specify a date value when creating or updating a member, the date needs to be converted to UTC first. &nbsp;Do not send a date without specifying timezone as it will be assumed to be UTC.
 +
 +
''Example'':&nbsp;We want to set JoinDate to be 2/14/2020 – make sure to specify the time and timezone offset like in the 2<sup>nd</sup> and 3<sup>rd</sup> examples:
 +
 +
''Example:''&nbsp;We want to set JoinDate to be 2/14/2020 – make sure to specify the time and timezone offset like in the 2<sup>nd</sup> and 3<sup>rd</sup> examples:
 +
 +
{| border="0" cellspacing="0" cellpadding="0"
 +
|-
 +
| style="width:208px;" |
 +
'''Value in JSON'''
 +
 +
| style="width:230px;" |
 +
'''DateTime value interpreted by API'''
 +
 +
| style="width:192px;" |
 +
'''Value saved in the database'''
 +
 +
|-
 +
| style="width:208px;" |
 +
2020-02-14
 +
 +
| style="width:230px;" |
 +
Feb 14, 2020 12 AM UTC
 +
 +
| style="width:192px;" |
 +
2020-02-13 19:00:00.000
 +
 +
|-
 +
| style="width:208px;" |
 +
2020-02-14T05:00:00Z
 +
 +
| style="width:230px;" |
 +
Feb 14, 2020 5 AM UTC
 +
 +
| style="width:192px;" |
 +
2020-02-14 00:00:00.000
 +
 +
|-
 +
| style="width:208px;" |
 +
2020-02-14T00:00:00-05:00
 +
 +
| style="width:230px;" |
 +
Feb 14, 2020 12 AM EST
 +
 +
| style="width:192px;" |
 +
2020-02-14 00:00:00.000
 +
 +
|}
 +
 +
&nbsp;To specify a date value when creating or updating a member, the date needs to be converted to UTC first. &nbsp;Do not send a date without specifying timezone as it will be assumed to be UTC.
 +
 +
&nbsp;''Example:''&nbsp;We want to set JoinDate to be 2/14/2020 – make sure to specify the time and timezone offset like in the 2<sup>nd</sup> and 3<sup>rd</sup> examples:
 +
 +
{| border="0" cellspacing="0" cellpadding="0"
 +
|-
 +
| style="width:208px;" |
 +
'''Value in JSON'''
 +
 +
| style="width:230px;" |
 +
'''DateTime value interpreted by API'''
 +
 +
| style="width:192px;" |
 +
'''Value saved in the database'''
 +
 +
|-
 +
| style="width:208px;" |
 +
2020-02-14
 +
 +
| style="width:230px;" |
 +
Feb 14, 2020 12 AM UTC
 +
 +
| style="width:192px;" |
 +
2020-02-13 19:00:00.000
 +
 +
|-
 +
| style="width:208px;" |
 +
2020-02-14T05:00:00Z
 +
 +
| style="width:230px;" |
 +
Feb 14, 2020 5 AM UTC
 +
 +
| style="width:192px;" |
 +
2020-02-14 00:00:00.000
 +
 +
|-
 +
| style="width:208px;" |
 +
2020-02-14T00:00:00-05:00
 +
 +
| style="width:230px;" |
 +
Feb 14, 2020 12 AM EST
 +
 +
| style="width:192px;" |
 +
2020-02-14 00:00:00.000
 +
 +
|}

Revision as of 16:50, 26 February 2020

Does a Member Exist?


Find out if a specific email address already exists in the site (get a SiteID). Send a GET request to the Members endpoint and include the email address in the $filter query string parameter.

Sample Request (Using 1234567890 as the SiteID):

GET http://services.fishbowl.com/api/odata/v1/SITE_ID/Members?$filter=EmailAddress
%20eq%20'johndoe@test.com' HTTP/1.1
Accept: application/json
Authorization: Bearer u7kBYz1UhHkoRSc7V4gruBs-4sEpIkFV-F4LGiFMwfGwJNnT_JzNft
g6_Zm0yWi8P m60iPlmCCHUSwCX5Uru-OJq2jzhbT-E6nAc1OwzghTCmeoo0K69ubDBMFX5hyKlc
AjA9H3Vs-ZNjNYKarpSO5rA5ubG5-Va5Aigm9mp-Pre-EaGAY_HBdxZi-LBMSQ_mSjyIDPBpLFYP
BNzK3cu0xGobGsFLxPtDG3urs_4abXZtvxN8wm9rpsgr


Sample Respone When a Member is New (Does not exist):

{ 
"odata.metadata":"http://services.fishbowl.com/API/odata/v1/1234567890/$metadata#Members",
"value":[]
}

Sample Respone When a Member Exists in the Database:

  { 
"odata.metadata":"http://services.fishbowl.com/API/odata/v1/2147483947/
        $metadata#Members",
"value":[ 
{ 
"MemberID":"2148166490",
"SiteID":"2147483947",
"EmailAddress":"johndoe@test.com",
"HardBounces":0,
"SoftBounces":0,
"Suppressed":false,
"IsTester":false,
"CreatedUtc":"2014-11-07T17:13:23.88Z",
"LastUpdatedUtc":"0001-01-01T05:00:00Z",
"StringFields":[ 
{ 
  "Name":"FirstName",
  "Value":"John" 
},
{ 
  "Name":"LastName",
  "Value":"Doe" 
},
{
  "Name":"StoreCode",
  "Value":"001" 
},
{
  "Name":"InputSource",
  "Value":"Partner" 
}
],
"BooleanFields":[],
"Int32Fields":[],
"Int64Fields":[],
"DateFields":[ 
{ 
  "Name":"Birthdate",
  "Value":"1999-04-03T00:00:00" 
},
{ 
  "Name":"Anniversary",
  "Value":null 
},
{ 
  "Name":"JoinDate",
  "Value":"2014-12-04T00:00:00.000" 
}
],
"DecimalFields":[],
"Subscriptions":[ 
{
  "ListID":"2147484225",
  "IsSubscribed":true
},
{
  "ListID":"2147485177",
  "IsSubscribed":true
}
],
"MemberTags":[] 
} 
] 
}

Adding a New Member

A new member can be created by sending a POST request to the Members endpoint and adding them to the correct list (get ListID) for the Site (Get a SiteID).

Note: if you try to create member with an email address that already exists, a 409 error (Conflict) will be returned.

Sample MERGE (Using SiteID - 1234567890 & ListID - 1122334455):

POST http://services.fishbowl.com/api/odata/v1/1234567890/Members HTTP/1.1
Accept: application/json
Authorization: Bearer u7kBYz1UhHkoRSc7V4gruBs-4sEpIkFV-F4LGiFMwfGwJNnT_JzNft
g6_Zm0yWi8P m60iPlmCCHUSwCX5Uru-OJq2jzhbT-E6nAc1OwzghTCmeoo0K69ubDBMFX5hyKlc
AjA9H3Vs-ZNjNYKarpSO5rA5ubG5-Va5Aigm9mp-Pre-EaGAY_HBdxZi-LBMSQ_mSjyIDPBpLFYP
BNzK3cu0xGobGsFLxPtDG3urs_4abXZtvxN8wm9rpsgr
Content-Type: application/json; charset=utf-8
{
"SiteID":"1234567890",
"EmailAddress":"johndoe@test.com",
"SubscriptionsForMember":[
{
"ListID":"1122334455",
"IsSubscribed":true
}
],
"StringFields":[
{
"Name":"FirstName",
"Value":"John"
},
{
"Name":"LastName",
"Value":"Doe"
},
{
"Name":"StoreCode",
"Value":"001"
},
{
"Name":"InputSource",
"Value":"Partner"
}
],
"DateFields":[
{
"Name":"Birthdate",
"Value":"1999-04-03T00:00:00"
},
{
"Name":"Anniversary",
"Value":null
},
{
"Name":"JoinDate",
"Value":"2014-12-04T00:00:00"
}
]
}

Updating a Member


To update the member record and/or subscribe the member to additional list(s), send a PATCH or MERGE request to the Members endpoint and include the member ID as parameter (Member ID can be obtained from the response).


The request URL will have the following format: http://services.fishbowl.com/API/odata/v1/SITE_ID/Members(MEMBER_IDL) Note the L following the MemberID, which is used to indicate 64-bit integer, e.g.: (2148166490L)


Sample POST (Using SiteID - 1234567890 & ListID - 1122334455)

MERGE http://services.fishbowl.com/API/odata/v1/1234567890/Members(MEMBER_IDL)
HTTP/1.1
Accept: application/json
Authorization: Bearer u7kBYz1UhHkoRSc7V4gruBs-4sEpIkFV-F4LGiFMwfGwJNnT_JzNft
g6_Zm0yWi8P m60iPlmCCHUSwCX5Uru-OJq2jzhbT-E6nAc1OwzghTCmeoo0K69ubDBMFX5hyKlc
AjA9H3Vs-ZNjNYKarpSO5rA5ubG5-Va5Aigm9mp-Pre-EaGAY_HBdxZi-LBMSQ_mSjyIDPBpLFYP
BNzK3cu0xGobGsFLxPtDG3urs_4abXZtvxN8wm9rpsgr
Content-Type: application/json; charset=utf-8
{
"SiteID":"1234567890",
"MemberID":"9876543210",
"EmailAddress":"johndoe@test.com",
"SubscriptionsForMember":[
{
"ListID":"1122334455",
"IsSubscribed":true         
}
],
"StringFields":[
{
"Name":"FirstName",
"Value":"John"
},
{
"Name":"LastName",
"Value":"Doe"
},
{
"Name":"StoreCode",
"Value":"001"
}
],
"DateFields":[
{
"Name":"Birthdate",
"Value":"1999-04-03T00:00:00"
},
{
"Name":"Anniversary",
"Value":"2009-02-14T00:00:00"
}
]
}

Dates & Date Conversion

Dates are stored on Fishbowl database using US Eastern Timezone.  However, the Enterprise REST API will convert datetime values to UTC. 

 If a Get request is issued for an existing member whose JoinDate value is 2/14/2020 12 AM in the database, the JSON returned by the API will be:

"DateFields": [

        {

          "Name": "JoinDate",

          "Value": "2020-02-14T05:00:00Z"

        }]

To specify a date value when creating or updating a member, the date needs to be converted to UTC first.  Do not send a date without specifying timezone as it will be assumed to be UTC.

Example: We want to set JoinDate to be 2/14/2020 – make sure to specify the time and timezone offset like in the 2nd and 3rd examples:

Example: We want to set JoinDate to be 2/14/2020 – make sure to specify the time and timezone offset like in the 2nd and 3rd examples:

Value in JSON

DateTime value interpreted by API

Value saved in the database

2020-02-14

Feb 14, 2020 12 AM UTC

2020-02-13 19:00:00.000

2020-02-14T05:00:00Z

Feb 14, 2020 5 AM UTC

2020-02-14 00:00:00.000

2020-02-14T00:00:00-05:00

Feb 14, 2020 12 AM EST

2020-02-14 00:00:00.000

 To specify a date value when creating or updating a member, the date needs to be converted to UTC first.  Do not send a date without specifying timezone as it will be assumed to be UTC.

 Example: We want to set JoinDate to be 2/14/2020 – make sure to specify the time and timezone offset like in the 2nd and 3rd examples:

Value in JSON

DateTime value interpreted by API

Value saved in the database

2020-02-14

Feb 14, 2020 12 AM UTC

2020-02-13 19:00:00.000

2020-02-14T05:00:00Z

Feb 14, 2020 5 AM UTC

2020-02-14 00:00:00.000

2020-02-14T00:00:00-05:00

Feb 14, 2020 12 AM EST

2020-02-14 00:00:00.000