Groups

REST API: Groups

Using the Groups REST API, you can create, search, update and view the full detail of groups within your AMS+ account.

When creating or updating field values that use a checkbox list or dropdown with user-defined values in Data & Custom Fields via API request, please note that any new values that did not previously exist will be automatically added.

Group Resources

• Create
• Search
• Detail
• Update

Create

RESOURCE URI

https://app.agencybloc.com/api/v1/groups/create

REQUIRED POST PARAMETERS

You must POST the following parameters via the body of the request. Parameters found in the querystring of the request will be ignored:

ADDITIONAL POST PARAMETERS

You may also POST any of the following parameters:

When sending gender via POST, please format using M for a male or F for a female. When sending email via POST, please ensure that all email addresses are formatted as name@example.com. When sending dates via POST, please ensure that the dates are formatted as 01/01/2013.

You may also POST account manager information for the new group using this parameter:

For the account manager field, you are allowed to pass in either the unique AMS+ user ID or the name, as it exactly appears within AMS+. To get the unique AMS+ user ID, navigate to 'Settings' -> 'User Administration'. Select the user you wish to be set as the account manager and you will be able to get the unique AMS+ user ID via the URL.

https://app.agencybloc.com/settings/user-administration/edit/###

The 'User ID' used by AMS+ is represented by the ### in the link above. By sending this value via POST, the API will assign the corresponding user as account manager to the new group being created.

You may also POST phone numbers for the new group using these parameters:

When sending phone numbers via POST, please ensure that all phone numbers are formatted as (319) 555-0000.

You may also POST address information for the new group using these parameters:

Note: You can also create, update and delete addresses using the Addresses API.

You may also POST agent information for the new group using these parameters:

To get the corresponding 'Agent ID' from AMS+, you will need to get the unique identifier used within AMS+. To get this value you will need to navigate to the 'Agent Detail' screen within AMS+. Once you have reached that page you can get the value from the URL:

https://app.agencybloc.com/agents/######/detail

The 'Agent ID' used by AMS+ is represented by the ###### in the link above. By sending this value via POST, the API will assign the corresponding agent to the new group being created.

When sending the agent's first and last name via POST, the agent's first and last name will need to match exactly as it appears within AMS+. If the names don't match exactly what is on file in AMS+, the agent will not be assigned.

Custom Fields

The REST API allows access to the custom fields inside your account when creating a new group. In order to pass custom fields via the REST API, you will need to preface the names of the custom fields inside your account with 'custom_'. To obtain the name values for the custom fields, you will need to access the custom fields page below.

https://app.agencybloc.com/settings/custom-fields/Group/list

By selecting the entity type from the dropdown, you will see the list of that entity's custom fields. All names must match exactly what is listed on the page, along with the preface of 'custom_'.

Note: When passing custom field data for Checkbox List custom fields, multiple values need to be separated by ||. For example, “option 1||option 2”.

RESPONSE

A return response will be generated after you have consumed the API. Upon successfully creating a new group inside your AMS+ account, you will get a return status of 200 along with the groupID as seen below.

{ 
  "Agencybloc Response": { 
     "Status":"200", 
     "groupID":"123456", 
     "Action":"create" 
  } 
}

Search

RESOURCE URI

https://app.agencybloc.com/api/v1/groups/search

REQUIRED POST PARAMETERS

There are no required POST parameters for searching. However, if you do not include any parameters the results are limited to 50 groups.

ADDITIONAL POST PARAMETERS

You may POST any of the following parameters to search for a group:

When sending dates via POST, please ensure that the dates are formatted as 01/01/2013. For updatedDTM and updatedDTMBefore, see Searching by date and time below for additional formats that include a time.

SEARCHING BY DATE AND TIME

Use updatedDTM and updatedDTMBefore to find groups updated within a window of time. You can send either parameter on its own, or send both together.

• If you do not include a UTC offset, the time is treated as Central Time. If you include an offset, it is honored and converted to Central Time.
• Include seconds (HH:mm:ss) whenever you send a time. Other date formats, such as 01/01/2013, are still accepted but are treated as date only, and any time in them is ignored.
• updatedDTMBefore is an exclusive upper bound, so groups updated at exactly that date and time are not returned. Use one window's updatedDTMBefore as the next window's updatedDTM to search back to back without gaps or overlap.
• When you send updatedDTM or updatedDTMBefore, results are returned in order of last update, oldest first. This makes limit return a predictable set of groups.
• Each result includes updatedDTM, the date and time of the group's last update in Central Time.
• Only changes to the group record itself update this date and time. Changes to related information, such as phone numbers, addresses, and custom fields, do not.

Daylight saving time: AMS+ stores update times in Central Time without a UTC offset. In the fall, when clocks move back, the hour from 1:00 AM to 1:59 AM occurs twice, and records saved during either occurrence have times in that range. In the spring, when clocks move forward, the hour from 2:00 AM to 2:59 AM does not occur. A UTC offset in your search is converted to Central Time before the search runs, so it does not distinguish the two occurrences of the repeated hour. If your integration searches on a schedule, search the repeated hour again each fall and use the record ID to remove duplicates.

If a value is not recognized, the API returns a 400 error that names the parameter and lists the accepted formats:

{
  "Agencybloc Response": {
     "Exception": {
        "Status":"400",
        "Title":"Invalid updatedDTM",
        "Message":"Expected yyyy-MM-dd, yyyy-MM-dd HH:mm:ss, yyyy-MM-ddTHH:mm:ss, or yyyy-MM-ddTHH:mm:ss with a UTC offset such as -05:00 or Z. Values without an offset are treated as US Central. Other recognized date formats such as MM/dd/yyyy are still accepted and are treated as date only; send one of the formats above to filter on a time of day."
     }
  }
}

RESPONSE

The response will be a list of groups matching your criteria in JSON format.

The detail_url is the url that can be used to retrieve the full detail of the group.

[ 
 { 
   "groupID":123456, 
   "groupName":"Test Company", 
   "type":"Client", 
   "businessPhone":"(123) 456 7890", 
   "fedTaxID":"11-1234567", 
   "updatedDTM":"1111-11-11T00:00:00", 
   "detail_url":"https://app.agencybloc./api/v1/groups/detail" 
 }, 

 { 
  "groupID":654321, 
  "groupName":"Example Company", 
  "type":"Client", 
  "businessPhone":"(987) 654 3210", 
  "fedTaxID":"11-7654321", 
  "updatedDTM":"1111-11-11T00:00:00", 
  "detail_url":"https://app.agencybloc.com/api/v1/groups/detail" 
 }
]

Detail

RESOURCE URI

https://app.agencybloc.com/api/v1/groups/detail

REQUIRED POST PARAMETERS

ADDITIONAL POST PARAMETERS

You may POST the following parameter to include activities for a group:

When sending includeActivities via POST, please format using 1 to include activities. Not passing in includeActivities or formatting using 0 will not return activities.

RESPONSE

The response will be the full detail of the group selected and include all addresses associated with group.

{
  "groupID": "123456",
  "groupName": "Example Group",
  "dba": "example",
  "fedTaxID": "99-9999999",
  "employees": "100",
  "description": "Description example",
  "website": "www.example.com",
  "groupType": "example",
  "projectCode": "example",
  "leadSource": "example",
  "leadSourceOther": "example",
  "leadSourceAgentName": "Firstname Lastname",
  "leadDate": "1111-11-11T00:00:00",
  "industry": "example",
  "accountManagerName": "Firstname, Lastname",
  "servicingAgentName": "Firstname, Lastname",
  "businessPhone": "(123) 456-7890",
  "fax": "(123) 456-7890",
  "addresses": [
    {
      "addressID": 12345,
      "entityID": 123456,
      "entityType": "Group",
      "addressType": "Business",
      "street1": "123 Example",
      "street2": "",
      "city": "Cedar Falls",
      "stateAbbrev": "IA",
      "zip": "50613"
    },
    {
      "addressID": 12345,
      "entityID": 123456,
      "entityType": "Group",
      "addressType": "Home",
      "street1": "123 Example",
      "street2": "",
      "city": "Cedar Falls",
      "stateAbbrev": "IA",
      "zip": "50613"
    }
  ],
  "policies": [
    {
      "PolicyID": 12345,
      "HolderID": 54321,
      "HolderType": "Group",
      "HolderName": "Example",
      "AgentID": 123,
      "AgentName": "Example",
      "AgentNumID": 1,
      "CarrierID": 1234,
      "CarrierName": "Example",
      "StatusLookupID": 3456,
      "StatusDescript": "Example",
      "SignedByAgentID": 6789,
      "SignedByAgentName": "Example",
      "AcctMgrUserID": 123,
      "AcctMgrName": "Example",
      "PolicyNumber": "Example",
      "EffectiveDate": "1111-01-01T00:00:00",
      "RenewalDate": "1111-01-01T00:00:00",
      "RenewalIncrease": 0,
      "TermDate": "1111-01-01T00:00:00",
      "Lives": 123,
      "Notes": "Example",
      "CommissionFreq": 0,
      "ClientID": 0,
      "Active": 1,
      "Deleted": 0,
      "CoverageTypeLookupID": 123,
      "CoverageTypeDescript": "Example",
      "Premium": 1000,
      "ProjectCodeLookupID": 4567,
      "ProjectCodeDescript": "Example",
      "AppSubmitDate": "1111-01-01T00:00:00",
      "PayFreq": 1
    }
  ],
  "activities":[ 
   { 
      "activity_id":1111,
      "activity_date":"2019-01-21",
      "subject":"Lorem Ipsum",
      "notes":"Lorem ipsum dolor sit amet.",
      "status":"In Progress",
      "type":"Renewal",
      "method":"Email",
      "priority":"Medium",
      "related_policy_id":0,
      "FU_user_id":0,
      "FU_user_first_name":"Firstname",
      "FU_user_last_name":"Lastname",
      "FU_team_name":"Team Name",
      "followup_allday":0,
      "FU_date":"2019-01-01",
      "FU_UTC_start_time":"14:00:00",
      "FU_UTC_end_time":"15:00:00"
   }
],
  "customFields": [
    {
      "Name": "Custom Field 1",
      "Value": [
        "Example"
      ]
    },
    {
      "Name": "Custom Field 2 (Multi-Select)",
      "Value": [
        "option 1||option 2"
      ]
    }
  ]
}

Note: If you want the full follow-up date and time, you will need to concatenate FU_date with the corresponding FU_UTC start/end time when consuming the API.

Update

RESOURCE URI

https://app.agencybloc.com/api/v1/groups/update

REQUIRED POST PARAMETERS

You must POST the following parameters via the body of the request. Parameters found in the querystring of the request will be ignored:

ADDITIONAL POST PARAMETERS

You may also POST any of the following parameters:

When sending gender via POST, please format using M for a male or F for a female. When sending email via POST, please ensure that all email addresses are formatted as name@example.com. When sending dates via POST, please ensure that the dates are formatted as 01/01/2013.

You may also POST account manager information for the group using this parameter:

For the account manager field, you are allowed to pass in either the unique AMS+ user ID or the name, as it exactly appears within AMS+. To get the unique AMS+ user ID, navigate to 'Settings' -> 'User Administration'. Select the user you wish to be set as the account manager and you will be able to get the unique AMS+ user ID via the URL.

https://app.agencybloc.com/settings/user-administration/edit/###

The 'User ID' used by AMS+ is represented by the ### in the link above. By sending this value via POST, the API will assign the corresponding user as account manager to the group being updated.

You may also POST phone numbers for the new group using these parameters:

When sending phone numbers via POST, please ensure that all phone numbers are formatted as (319) 555-0000.

Note: You may also update addresses for the group using the Addresses API.

You may also POST agent information for the new group using these parameters:

To get the corresponding 'Agent ID' from AMS+, you will need to get the unique identifier used within AMS+. To get this value you will need to navigate to the 'Agent Detail' screen within AMS+. Once you have reached that page you can get the value from the URL:

https://app.agencybloc.com/agents/######/detail

The 'Agent ID' used by AMS+ is represented by the ###### in the link above. By sending this value via POST, the API will assign the corresponding agent to the new group being created.

When sending the agent's first and last name via POST, the agent's first and last name will need to match exactly as it appears within AMS+. If the names don't match exactly what is on file in AMS+, the agent will not be assigned.

Custom Fields

The REST API allows access to the custom fields inside your account when updating a group. In order to pass custom fields via the REST API, you will need to preface the names of the custom fields inside your account with 'custom_'. To obtain the name values for the custom fields, you will need to access the custom fields page below.

https://app.agencybloc.com/settings/custom-fields/Group/list

By selecting the entity type from the dropdown, you will see the list of that entity's custom fields. All names must match exactly what is listed on the page, along with the preface of 'custom_'.

Note: When passing custom field data for Checkbox List custom fields, multiple values need to be separated by ||. For example, “option 1||option 2”.

RESPONSE

A return response will be generated after you have consumed the API. Upon successfully updating a group inside your AMS+ account, you will get a return status of 200 along with the groupID as seen below.

{ 
  "Agencybloc Response": { 
     "Status":"200", 
     "groupID":"123456", 
     "Action":"update" 
  } 
}

Exception Responses

The exception responses will include status, title, and message and be in JSON format.

{
  "Agencybloc Response": { 
     "Exception": { 
        "Status":"Status Code",
        "Title":"Title of Error",
        "Message":"Error Message"
  }
}