Create a lead

Introduction

Welcome to the WeGroup Documentation Platform for pushing leads to our API. This guide will walk you through the process of integrating your broker platform with WeGroup to enrich data by pushing leads.

A lead is a also known as a party or prospect in WeGroup, the difference is that a lead contains extra metadata (origin, backref, source).

Use cases

• As a broker platform you want to push leads to WeGroup to enrich data.

API Documentation

To access the API documentation for pushing leads, please refer to the following links based on the environment:

How to

When adding a callback to the payload you will receive webhooks, this way you can receive updates on the created lead.

It is recommended to include an external_ref to establish a direct link between the ID given to the lead in your platform and WeGroup.

Adding origin and backref enhances integration, where origin indicates the source of the lead, and backref is a clickable link in WeGroup, allowing seamless navigation between WeGroup and your platform.

Create a customer lead

curl -X POST \
    "https://$HOST/v1/api/distributions/$DISTRIBUTION_ID/leads/customers" \
    -H "Authorization: apikey $API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "origin": "CRM",
        "backref": "https://backref/prospects/1",
        "prospect": {
            "first_name": "Foo",
            "last_name": "Bar"
            "callbacks": ["https://callback.com"],
            "external_ref": {
                "external_ref": "123",
                "external_ref_company": "company"
            },
            "risk_objects": {"cars": [{"vin": WBA6L7100LFH65459}]}
        }
    }'

curl -X POST \
    "https://$HOST/v1/api/distributions/$DISTRIBUTION_ID/leads/customers" \
    -H "Authorization: bearer $ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "origin": "CRM",
        "backref": "https://backref/prospects/1",
        "prospect": {
            "first_name": "Foo",
            "last_name": "Bar"
            "callbacks": ["https://callback.com"],
            "external_ref": {
                "external_ref": "123",
                "external_ref_company": "company"
            },
            "risk_objects": {"cars": [{"vin": WBA6L7100LFH65459}]}
        }
    }'

Response:

{
  "id": "684451bd-8ae5-498a-9bee-d48d2462f20c",
  ...
}

Create a company lead

curl -X POST \
    "https://$HOST/v1/api/distributions/$DISTRIBUTION_ID/leads/companies" \
    -H "Authorization: apikey $API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "origin": "CRM",
        "backref": "https://backref/prospects/1",
        "prospect": {
            "name": "Foo",
            "callbacks": ["https://callback.com"],
            "external_ref": {
                "external_ref": "123",
                "external_ref_company": "company"
            },
            "risk_objects": {"cars": [{"vin": WBA6L7100LFH65459}]}
        }
    }'

curl -X POST \
    "https://$HOST/v1/api/distributions/$DISTRIBUTION_ID/leads/companies" \
    -H "Authorization: bearer $ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "origin": "CRM",
        "backref": "https://backref/prospects/1",
        "prospect": {
            "name": "Foo",
            "callbacks": ["https://callback.com"],
            "external_ref": {
                "external_ref": "123",
                "external_ref_company": "company"
            },
            "risk_objects": {"cars": [{"vin": WBA6L7100LFH65459}]}
        }
    }'

Response:

{
  "id": "684451bd-8ae5-498a-9bee-d48d2462f20c",
  ...
}

Create a lead with insurances policies and packages

The following example will create a Company party with 1 insurance policy which is part of a package. The important part is the identifier is a uuid to link insurance policies to package and risk objects to coverages in the same API call.

UUIDv4_1=`uuidgen`
UUIDv4_2=`uuidgen`

curl -X POST \
    "https://$HOST/v1/api/distributions/$DISTRIBUTION_ID/leads/companies" \
    -H "Authorization: apikey $ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "origin": "CRM",
        "backref": "https://backref/prospects/1",
        "prospect": {
            "name": "FooBar",
            "callbacks": ["https://callback.com"],
            "external_ref": {
                "external_ref": "123",
                "external_ref_company": "brokercloud"
            },
            "risk_objects": {
                "cars": [
                    {
                        "id": "'$UUIDv4_2'",
                        "vin": "WBA6L7100LFH65459"
                    }
                ]
            },
            "policy_packages": [
                {
                    "name": "Package 1",
                    "package_nr": "123",
                    "insurance_company": "Allianz",
                    "premium": "100",
                    "payment_interval": "ANNUAL",
                    "id": "'$UUIDv4_1'"
                }
            ],
            "insurance_policies": [
                {
                    "name": "Polis 1",
                    "policy_nr": "123",
                    "policy_package_id": "'$UUIDv4_1'",
                    "type": "ACTIVE",
                    "insurance_company": "Allianz",
                    "external_refs": [
                        {"company": "Allianz", "ref": "123"}
                    ],
                    "coverages": [
                        {
                            "external_label": {"label": "2010", "type": "AFD"},
                            "name": "WA",
                            "risk_object_id": "'$UUIDv4_2'",
                            "insured_value": 100.0,
                            "premium": "300",
                            "payment_interval": "ANNUAL"
                        }
                    ]
                }
            ]
        }
    }'

Updating a lead

WeGroup merges data together if matching data is found, this to prevent duplicate entries in the system.

This means that you can use the create lead endpoint again to update data.

A data merge is done by the following combinations of data that have an exact match:

• distribution_id and external_ref
• distribution_id and id
• distribution_id, email, birth and address

Add insurances

TODO

Errors

WeGroup uses HTTP status codes to indicate whether an API request failed or succeeded. In general, these response codes can be divided in the following ranges:

• 2xx: This range indicates a successful API request. Everything works as expected.
• 4xx: This range indicates a failed API request due to the request being malformed or invalid.
• 5xx: This range indicates a failed API request due to an unexpected error on WeGroup's end.

In addition to the HTTP response codes, the response body of a failed request contains a more detailed description on the error to provide some inside on what went wrong. Although the results may vary based on the type of error, the detailed error information of a failed request typically looks like the following:

"detail": {
    "type": "ValidationError",
    "errors": [
        {
            "type": "ValidationError",
            "target": "name",
            "message": "Error for 'name'. This value is missing"
        },
    ],
    "error_str": "3 validation errors for ..."
}

Where

• type: Provides a general indication of the type of error that occurred.
• errors: A collection of error objects providing as much detailed information on the error as possible.
  • type: The type of error that occurred.
  • target: Indicates the source of the error through a path of connected attributes. This path can be mapped back to the payload of the failing request.
  • message: A human-readable description of the error. Ideal for both end customers as consumers of the API to know what went wrong exactly. If supported the content of this message is localized based on the (preferred) language of the user.
• error_str: The string representation of the error that occurred.

Validation errors

Validation errors occur whenever the provided request was unacceptable, often due to a missing but required parameters or by providing an invalid or malformed payload. The included information on the error in the response should provide enough information to identify and resolve the bad part of the request. Typically the detailed information on the failed validation is included in the errors attribute of the response body. An example of a validation error and how to interpret the response is depicted below.

...
"type": "ValidationError",
    "errors": [
        {
        "type": "ValidationError",
        "target": "risk_objects.residences.0.address.zipcode",
        "message": "Error for 'zipcode'. The specified value is invalid."
    },
    {
        "type": "ValidationError",
        "target": "risk_objects.residences.0.address.housenr",
        "message": "Error for 'housenr'. The specified value does not meet the minimum length. (1)"
    },
    {
        "type": "ValidationError",
        "target": "risk_objects.residences.0.address.city",
        "message": "Error for 'city'. The specified value does not meet the minimum length. (1)"
    }
    ],
    "error_str": "3 validation errors for ... "
...

The example response of a validation error indicates the request was not accepted and three different issues were identified when processing the payload. The first entry inside errors provides enough information to identify what went wrong:

    {
    "type": "ValidationError",
    "target": "risk_objects.residences.0.address.zipcode",
    "message": "Error for 'zipcode'. The specified value is invalid."
},

• type: The request failed due to the provided payload being invalid or malformed.
• message: The validation failed on the postcode (zipcode) attribute. The second part of the message provides information on why the provided value for postcode (zipcode) was not accepted.
• target: Provides enough information to track down the exact location of the postcode (zipcode) attribute in the request payload that caused the request to fail. Based on the value of target in this example, the postcode (zipcode) attribute was located at the address object of the first entry (0) in the residences collection inside the risk_objects object.

...
{
    "risk_objects": {
        "residences": [
                {
                    "address": {
                        "zipcode": "ERROR",
                        ...
                    },
                },
                ...

            ]
        ...
    },
    ...
}
...

Extending the journey

After creating a lead, you can:

• start a conversation here
• start a campaign here
• Capture events here