Identity Verification and Message Engagement Registration

Wrapper for various Identity Verification services and Message Engagement Platforms

Download OpenAPI Specification

Identities

APIs relating to working with Identities

Available Operations

Retrieve all of the identities associated with your account.

List identities

gethttps://api.nexmo.com/v1/messaging-engagement/identities

Responses
Content Type
application/json

List of brands that are associated with an account

page_size

integer

example10

Items per page

page

integer

Min1

example2

Page Offset

total_pages

integer

Min1

example100

Number of pages in the entire result set

total_items

integer

example100

Number of items in the entire result set

_embedded

object

brands

array

entity_type

string

examplePUBLIC_PROFIT

Must be one of:INDIVIDUALPRIVATE_PROFITPUBLIC_PROFICNON_PROFIT

display_name

string

exampleVonage

company_name

string

exampleVonage

ein

string

example20-1111111

alt_business_id_type

string

exampleDUNS

alt_business_id

string

example150483782

phone

string

example+15556660001

street

string

example23 Main Street

city

string

exampleHolmdel

state

string

exampleNJ

postal_code

string

example07733

country

string

exampleUS

string

exampledevrel@vonage.com

stock_symbol

string

exampleVG

stock_exchange

string

exampleNASDAQ

website

string

examplehttps://vonage.com

brand_relationship

string

exampleKEY_ACCOUNT

Must be one of:BASIC_ACCOUNTSMALL_ACCOUNTMEDIUM_ACCOUNTLARGE_ACCOUNTKEY_ACCOUNT

vertical

string

exampleTECHNOLOGY

identity_id

string

exampleBLQKOPK

Identity ID associated with a number

created_date

string

example2020-01-02 05:12:14

last_updated

string

example2020-02-02 14:12:00

_links

object

self

object

href

string

examplehttps://api.nexmo.com/v1/messaging-engagement/identities/BLQKOPK

engagements

object

href

string

examplehttps://api.nexmo.com/v1/messaging-envagement/engagements/?identity_id=BLQKOPK

Example Response

{
   "page_size": 10,
   "page": 2,
   "total_pages": 100,
   "total_items": 100,
   "_embedded": {
      "brands": [
         {
            "entity_type": "PUBLIC_PROFIT",
            "display_name": "Vonage",
            "company_name": "Vonage",
            "ein": "20-1111111",
            "alt_business_id_type": "DUNS",
            "alt_business_id": "150483782",
            "phone": "+15556660001",
            "street": "23 Main Street",
            "city": "Holmdel",
            "state": "NJ",
            "postal_code": "07733",
            "country": "US",
            "email": "devrel@vonage.com",
            "stock_symbol": "VG",
            "stock_exchange": "NASDAQ",
            "website": "https://vonage.com",
            "brand_relationship": "KEY_ACCOUNT",
            "vertical": "TECHNOLOGY",
            "identity_id": "BLQKOPK",
            "created_date": "2020-01-02 05:12:14",
            "last_updated": "2020-02-02 14:12:00",
            "_links": {
               "self": {
                  "href": "https://api.nexmo.com/v1/messaging-engagement/identities/BLQKOPK"
               },
               "engagements": {
                  "href": "https://api.nexmo.com/v1/messaging-envagement/engagements/?identity_id=BLQKOPK"
               }
            }
         }
      ]
   }
}

Create a new identity for your account

Create a new identity for your account. Most accounts will be created immediately, and you can move on to qualifying a new engagement for the identity. Some brands may require additional vetting. In such cases, please move on to the vetting API endpoints before attempting to create an engagement.

Please note the entity_type field, as that field value will help determine which fields are required.

posthttps://api.nexmo.com/v1/messaging-engagement/identities

Request Body
Content Type
application/json

One Of

entity_type

string

Required

examplePUBLIC_PROFIT

Must be one of:INDIVIDUALPRIVATE_PROFITPUBLIC_PROFICNON_PROFIT

display_name

string

Required

exampleVonage

company_name

string

exampleVonage

ein

string

example20-1111111

alt_business_id_type

string

exampleDUNS

alt_business_id

string

example150483782

phone

string

Required

example+15556660001

street

string

example23 Main Street

city

string

exampleHolmdel

state

string

exampleNJ

postal_code

string

example07733

country

string

Required

exampleUS

string

Required

exampledevrel@vonage.com

stock_symbol

string

exampleVG

stock_exchange

string

exampleNASDAQ

website

string

examplehttps://vonage.com

brand_relationship

string

Required

exampleKEY_ACCOUNT

Must be one of:BASIC_ACCOUNTSMALL_ACCOUNTMEDIUM_ACCOUNTLARGE_ACCOUNTKEY_ACCOUNT

vertical

string

exampleTECHNOLOGY

Example Request

{
   "entity_type": "PUBLIC_PROFIT",
   "display_name": "Vonage",
   "company_name": "Vonage",
   "ein": "20-1111111",
   "alt_business_id_type": "DUNS",
   "alt_business_id": "150483782",
   "phone": "+15556660001",
   "street": "23 Main Street",
   "city": "Holmdel",
   "state": "NJ",
   "postal_code": "07733",
   "country": "US",
   "email": "devrel@vonage.com",
   "stock_symbol": "VG",
   "stock_exchange": "NASDAQ",
   "website": "https://vonage.com",
   "brand_relationship": "KEY_ACCOUNT",
   "vertical": "TECHNOLOGY"
}

{
   "entity_type": "PUBLIC_PROFIT",
   "display_name": "Vonage",
   "company_name": "Vonage",
   "ein": "20-1111111",
   "alt_business_id_type": "DUNS",
   "alt_business_id": "150483782",
   "phone": "+15556660001",
   "street": "23 Main Street",
   "city": "Holmdel",
   "state": "NJ",
   "postal_code": "07733",
   "country": "US",
   "email": "devrel@vonage.com",
   "stock_symbol": "VG",
   "stock_exchange": "NASDAQ",
   "website": "https://vonage.com",
   "brand_relationship": "KEY_ACCOUNT",
   "vertical": "TECHNOLOGY"
}

Responses
Content Type
application/json

Return a single identity

entity_type

string

examplePUBLIC_PROFIT

Must be one of:INDIVIDUALPRIVATE_PROFITPUBLIC_PROFICNON_PROFIT

display_name

string

exampleVonage

company_name

string

exampleVonage

ein

string

example20-1111111

alt_business_id_type

string

exampleDUNS

alt_business_id

string

example150483782

phone

string

example+15556660001

street

string

example23 Main Street

city

string

exampleHolmdel

state

string

exampleNJ

postal_code

string

example07733

country

string

exampleUS

string

exampledevrel@vonage.com

stock_symbol

string

exampleVG

stock_exchange

string

exampleNASDAQ

website

string

examplehttps://vonage.com

brand_relationship

string

exampleKEY_ACCOUNT

Must be one of:BASIC_ACCOUNTSMALL_ACCOUNTMEDIUM_ACCOUNTLARGE_ACCOUNTKEY_ACCOUNT

vertical

string

exampleTECHNOLOGY

identity_id

string

exampleBLQKOPK

Identity ID associated with a number

created_date

string

example2020-01-02 05:12:14

last_updated

string

example2020-02-02 14:12:00

_links

object

self

object

href

string

example

[
  "https://api.nexmo.com/v1/messaging-engagement/identities/BLQKOPK",
  "/v1/messaging-engagement/identities/5782db87-a867-4ccd-a0b5-1b7203cc438c"
]

engagements

object

href

string

examplehttps://api.nexmo.com/v1/messaging-envagement/engagements/?identity_id=BLQKOPK

Example Response

{
   "entity_type": "PUBLIC_PROFIT",
   "display_name": "Vonage",
   "company_name": "Vonage",
   "ein": "20-1111111",
   "alt_business_id_type": "DUNS",
   "alt_business_id": "150483782",
   "phone": "+15556660001",
   "street": "23 Main Street",
   "city": "Holmdel",
   "state": "NJ",
   "postal_code": "07733",
   "country": "US",
   "email": "devrel@vonage.com",
   "stock_symbol": "VG",
   "stock_exchange": "NASDAQ",
   "website": "https://vonage.com",
   "brand_relationship": "KEY_ACCOUNT",
   "vertical": "TECHNOLOGY",
   "identity_id": "BLQKOPK",
   "created_date": "2020-01-02 05:12:14",
   "last_updated": "2020-02-02 14:12:00",
   "_links": {
      "self": {
         "href": "/v1/messaging-engagement/identities/5782db87-a867-4ccd-a0b5-1b7203cc438c"
      },
      "engagements": {
         "href": "https://api.nexmo.com/v1/messaging-envagement/engagements/?identity_id=BLQKOPK"
      }
   }
}

Retrieve a specific identity

Get an identity

gethttps://api.nexmo.com/v1/messaging-engagement/identities/:identity_id

Path Parameters

identity_id

string

Required

exampleBLQKOPK

Identity ID associated with a number

Responses
Content Type
application/json

Return a single identity

entity_type

string

examplePUBLIC_PROFIT

Must be one of:INDIVIDUALPRIVATE_PROFITPUBLIC_PROFICNON_PROFIT

display_name

string

exampleVonage

company_name

string

exampleVonage

ein

string

example20-1111111

alt_business_id_type

string

exampleDUNS

alt_business_id

string

example150483782

phone

string

example+15556660001

street

string

example23 Main Street

city

string

exampleHolmdel

state

string

exampleNJ

postal_code

string

example07733

country

string

exampleUS

string

exampledevrel@vonage.com

stock_symbol

string

exampleVG

stock_exchange

string

exampleNASDAQ

website

string

examplehttps://vonage.com

brand_relationship

string

exampleKEY_ACCOUNT

Must be one of:BASIC_ACCOUNTSMALL_ACCOUNTMEDIUM_ACCOUNTLARGE_ACCOUNTKEY_ACCOUNT

vertical

string

exampleTECHNOLOGY

identity_id

string

exampleBLQKOPK

Identity ID associated with a number

created_date

string

example2020-01-02 05:12:14

last_updated

string

example2020-02-02 14:12:00

_links

object

self

object

href

string

example

[
  "https://api.nexmo.com/v1/messaging-engagement/identities/BLQKOPK",
  "/v1/messaging-engagement/identities/5782db87-a867-4ccd-a0b5-1b7203cc438c"
]

engagements

object

href

string

examplehttps://api.nexmo.com/v1/messaging-envagement/engagements/?identity_id=BLQKOPK

Example Response

{
   "entity_type": "PUBLIC_PROFIT",
   "display_name": "Vonage",
   "company_name": "Vonage",
   "ein": "20-1111111",
   "alt_business_id_type": "DUNS",
   "alt_business_id": "150483782",
   "phone": "+15556660001",
   "street": "23 Main Street",
   "city": "Holmdel",
   "state": "NJ",
   "postal_code": "07733",
   "country": "US",
   "email": "devrel@vonage.com",
   "stock_symbol": "VG",
   "stock_exchange": "NASDAQ",
   "website": "https://vonage.com",
   "brand_relationship": "KEY_ACCOUNT",
   "vertical": "TECHNOLOGY",
   "identity_id": "BLQKOPK",
   "created_date": "2020-01-02 05:12:14",
   "last_updated": "2020-02-02 14:12:00",
   "_links": {
      "self": {
         "href": "/v1/messaging-engagement/identities/5782db87-a867-4ccd-a0b5-1b7203cc438c"
      },
      "engagements": {
         "href": "https://api.nexmo.com/v1/messaging-envagement/engagements/?identity_id=BLQKOPK"
      }
   }
}

Partially update a specific identity

Partial update of an identity

patchhttps://api.nexmo.com/v1/messaging-engagement/identities/:identity_id

Path Parameters

identity_id

string

Required

exampleBLQKOPK

Identity ID associated with a number

Request Body
Content Type
application/json

entity_type

string

examplePUBLIC_PROFIT

Must be one of:INDIVIDUALPRIVATE_PROFITPUBLIC_PROFICNON_PROFIT

display_name

string

exampleVonage

website

string

examplehttps://vonage.com

phone

string

example+15556660001

street

string

example23 Main Street

city

string

exampleHolmdel

state

string

exampleNJ

postal_code

string

example07733

country

string

exampleUS

string

exampledevrel@vonage.com

stock_symbol

string

exampleVG

stock_exchange

string

exampleNASDAQ

brand_relationship

string

exampleKEY_ACCOUNT

vertical

string

exampleTECHNOLOGY

Example Request

{
   "entity_type": "PUBLIC_PROFIT",
   "display_name": "Vonage",
   "website": "https://vonage.com",
   "phone": "+15556660001",
   "street": "23 Main Street",
   "city": "Holmdel",
   "state": "NJ",
   "postal_code": "07733",
   "country": "US",
   "email": "devrel@vonage.com",
   "stock_symbol": "VG",
   "stock_exchange": "NASDAQ",
   "brand_relationship": "KEY_ACCOUNT",
   "vertical": "TECHNOLOGY"
}

{
   "entity_type": "PUBLIC_PROFIT",
   "display_name": "Vonage",
   "website": "https://vonage.com",
   "phone": "+15556660001",
   "street": "23 Main Street",
   "city": "Holmdel",
   "state": "NJ",
   "postal_code": "07733",
   "country": "US",
   "email": "devrel@vonage.com",
   "stock_symbol": "VG",
   "stock_exchange": "NASDAQ",
   "brand_relationship": "KEY_ACCOUNT",
   "vertical": "TECHNOLOGY"
}

Responses
Content Type
application/json

Return a single identity

entity_type

string

examplePUBLIC_PROFIT

Must be one of:INDIVIDUALPRIVATE_PROFITPUBLIC_PROFICNON_PROFIT

display_name

string

exampleVonage

company_name

string

exampleVonage

ein

string

example20-1111111

alt_business_id_type

string

exampleDUNS

alt_business_id

string

example150483782

phone

string

example+15556660001

street

string

example23 Main Street

city

string

exampleHolmdel

state

string

exampleNJ

postal_code

string

example07733

country

string

exampleUS

string

exampledevrel@vonage.com

stock_symbol

string

exampleVG

stock_exchange

string

exampleNASDAQ

website

string

examplehttps://vonage.com

brand_relationship

string

exampleKEY_ACCOUNT

Must be one of:BASIC_ACCOUNTSMALL_ACCOUNTMEDIUM_ACCOUNTLARGE_ACCOUNTKEY_ACCOUNT

vertical

string

exampleTECHNOLOGY

identity_id

string

exampleBLQKOPK

Identity ID associated with a number

created_date

string

example2020-01-02 05:12:14

last_updated

string

example2020-02-02 14:12:00

_links

object

self

object

href

string

example

[
  "https://api.nexmo.com/v1/messaging-engagement/identities/BLQKOPK",
  "/v1/messaging-engagement/identities/5782db87-a867-4ccd-a0b5-1b7203cc438c"
]

engagements

object

href

string

examplehttps://api.nexmo.com/v1/messaging-envagement/engagements/?identity_id=BLQKOPK

Example Response

{
   "entity_type": "PUBLIC_PROFIT",
   "display_name": "Vonage",
   "company_name": "Vonage",
   "ein": "20-1111111",
   "alt_business_id_type": "DUNS",
   "alt_business_id": "150483782",
   "phone": "+15556660001",
   "street": "23 Main Street",
   "city": "Holmdel",
   "state": "NJ",
   "postal_code": "07733",
   "country": "US",
   "email": "devrel@vonage.com",
   "stock_symbol": "VG",
   "stock_exchange": "NASDAQ",
   "website": "https://vonage.com",
   "brand_relationship": "KEY_ACCOUNT",
   "vertical": "TECHNOLOGY",
   "identity_id": "BLQKOPK",
   "created_date": "2020-01-02 05:12:14",
   "last_updated": "2020-02-02 14:12:00",
   "_links": {
      "self": {
         "href": "/v1/messaging-engagement/identities/5782db87-a867-4ccd-a0b5-1b7203cc438c"
      },
      "engagements": {
         "href": "https://api.nexmo.com/v1/messaging-envagement/engagements/?identity_id=BLQKOPK"
      }
   }
}

Update a specific identity

Update an identity

puthttps://api.nexmo.com/v1/messaging-engagement/identities/:identity_id

Path Parameters

identity_id

string

Required

exampleBLQKOPK

Identity ID associated with a number

Request Body
Content Type
application/json

entity_type

string

examplePUBLIC_PROFIT

Must be one of:INDIVIDUALPRIVATE_PROFITPUBLIC_PROFICNON_PROFIT

display_name

string

exampleVonage

website

string

examplehttps://vonage.com

phone

string

example+15556660001

street

string

example23 Main Street

city

string

exampleHolmdel

state

string

exampleNJ

postal_code

string

example07733

country

string

exampleUS

string

exampledevrel@vonage.com

stock_symbol

string

exampleVG

stock_exchange

string

exampleNASDAQ

brand_relationship

string

exampleKEY_ACCOUNT

vertical

string

exampleTECHNOLOGY

Example Request

{
   "entity_type": "PUBLIC_PROFIT",
   "display_name": "Vonage",
   "website": "https://vonage.com",
   "phone": "+15556660001",
   "street": "23 Main Street",
   "city": "Holmdel",
   "state": "NJ",
   "postal_code": "07733",
   "country": "US",
   "email": "devrel@vonage.com",
   "stock_symbol": "VG",
   "stock_exchange": "NASDAQ",
   "brand_relationship": "KEY_ACCOUNT",
   "vertical": "TECHNOLOGY"
}

{
   "entity_type": "PUBLIC_PROFIT",
   "display_name": "Vonage",
   "website": "https://vonage.com",
   "phone": "+15556660001",
   "street": "23 Main Street",
   "city": "Holmdel",
   "state": "NJ",
   "postal_code": "07733",
   "country": "US",
   "email": "devrel@vonage.com",
   "stock_symbol": "VG",
   "stock_exchange": "NASDAQ",
   "brand_relationship": "KEY_ACCOUNT",
   "vertical": "TECHNOLOGY"
}

Responses
Content Type
application/json

Return a single identity

entity_type

string

examplePUBLIC_PROFIT

Must be one of:INDIVIDUALPRIVATE_PROFITPUBLIC_PROFICNON_PROFIT

display_name

string

exampleVonage

company_name

string

exampleVonage

ein

string

example20-1111111

alt_business_id_type

string

exampleDUNS

alt_business_id

string

example150483782

phone

string

example+15556660001

street

string

example23 Main Street

city

string

exampleHolmdel

state

string

exampleNJ

postal_code

string

example07733

country

string

exampleUS

string

exampledevrel@vonage.com

stock_symbol

string

exampleVG

stock_exchange

string

exampleNASDAQ

website

string

examplehttps://vonage.com

brand_relationship

string

exampleKEY_ACCOUNT

Must be one of:BASIC_ACCOUNTSMALL_ACCOUNTMEDIUM_ACCOUNTLARGE_ACCOUNTKEY_ACCOUNT

vertical

string

exampleTECHNOLOGY

identity_id

string

exampleBLQKOPK

Identity ID associated with a number

created_date

string

example2020-01-02 05:12:14

last_updated

string

example2020-02-02 14:12:00

_links

object

self

object

href

string

example

[
  "https://api.nexmo.com/v1/messaging-engagement/identities/BLQKOPK",
  "/v1/messaging-engagement/identities/5782db87-a867-4ccd-a0b5-1b7203cc438c"
]

engagements

object

href

string

examplehttps://api.nexmo.com/v1/messaging-envagement/engagements/?identity_id=BLQKOPK

Example Response

{
   "entity_type": "PUBLIC_PROFIT",
   "display_name": "Vonage",
   "company_name": "Vonage",
   "ein": "20-1111111",
   "alt_business_id_type": "DUNS",
   "alt_business_id": "150483782",
   "phone": "+15556660001",
   "street": "23 Main Street",
   "city": "Holmdel",
   "state": "NJ",
   "postal_code": "07733",
   "country": "US",
   "email": "devrel@vonage.com",
   "stock_symbol": "VG",
   "stock_exchange": "NASDAQ",
   "website": "https://vonage.com",
   "brand_relationship": "KEY_ACCOUNT",
   "vertical": "TECHNOLOGY",
   "identity_id": "BLQKOPK",
   "created_date": "2020-01-02 05:12:14",
   "last_updated": "2020-02-02 14:12:00",
   "_links": {
      "self": {
         "href": "/v1/messaging-engagement/identities/5782db87-a867-4ccd-a0b5-1b7203cc438c"
      },
      "engagements": {
         "href": "https://api.nexmo.com/v1/messaging-envagement/engagements/?identity_id=BLQKOPK"
      }
   }
}

Remove a specific identity from your account

Delete an identity

deletehttps://api.nexmo.com/v1/messaging-engagement/identities/:identity_id

Path Parameters

identity_id

string

Required

exampleBLQKOPK

Identity ID associated with a number

Responses

No content

Engagements

APIs relating to working with Engagements

Available Operations

Retrieve all of the engagements

List engagements

gethttps://api.nexmo.com/v1/messaging-engagement/engagements

Responses
Content Type
application/json

List of engagements that are associated with an identity

page_size

integer

example10

Items per page

page

integer

Min1

example2

Page Offset

total_pages

integer

Min1

example100

Number of pages in the entire result set

total_items

integer

example100

Number of items in the entire result set

_embedded

object

brands

array

identity_id

string

exampleBLQKOPK

Identity ID associated with a number

vertical

string

exampleTECHNOLOGY

use_case

string

exampleACCOUNT_NOTIFICATION

sub_use_cases

array

reseller_id

string

examplestring

description

string

exampleUser notifications

embedded_link

boolean

embedded_phone

boolean

number_pool

boolean

age_gated

boolean

exampletrue

direct_lending

boolean

exampletrue

subscriber_optin

boolean

subscriber_optout

boolean

subscriber_help

boolean

sample_one

string

exampleSample Message

sample_two

string

exampleAdditional Sample Message

sample_three

string

exampleAdditional Sample Message

sample_four

string

exampleAdditional Sample Message

message_flow

string

examplestring

help_message

string

examplestring

affiliate_marketing

boolean

exampletrue

engagement_id

string

exampleC1DEB879

ID associated with a specific engagement

created_date

string

last_updated

string

_links

object

self

object

href

string

numbers

object

href

string

Example Response

{
   "page_size": 10,
   "page": 2,
   "total_pages": 100,
   "total_items": 100,
   "_embedded": {
      "brands": [
         {
            "identity_id": "BLQKOPK",
            "vertical": "TECHNOLOGY",
            "use_case": "ACCOUNT_NOTIFICATION",
            "sub_use_cases": [
               "2FA",
               "SECURITY_ALERT"
            ],
            "reseller_id": "string",
            "description": "User notifications",
            "embedded_link": false,
            "embedded_phone": false,
            "number_pool": false,
            "age_gated": true,
            "direct_lending": true,
            "subscriber_optin": false,
            "subscriber_optout": false,
            "subscriber_help": false,
            "sample_one": "Sample Message",
            "sample_two": "Additional Sample Message",
            "sample_three": "Additional Sample Message",
            "sample_four": "Additional Sample Message",
            "message_flow": "string",
            "help_message": "string",
            "affiliate_marketing": true,
            "engagement_id": "C1DEB879",
            "created_date": "string",
            "last_updated": "string",
            "_links": {
               "self": {
                  "href": "string"
               },
               "numbers": {
                  "href": "string"
               }
            }
         }
      ]
   }
}

Add a new engagement to an identity

Create Engagement

posthttps://api.nexmo.com/v1/messaging-engagement/engagements

Request Body
Content Type
application/json

identity_id

string

Required

exampleBLQKOPK

Identity ID associated with a number

vertical

string

Required

exampleTECHNOLOGY

use_case

string

Required

exampleACCOUNT_NOTIFICATION

sub_use_cases

array

reseller_id

string

examplestring

description

string

Required

exampleUser notifications

embedded_link

boolean

embedded_phone

boolean

number_pool

boolean

age_gated

boolean

exampletrue

direct_lending

boolean

exampletrue

subscriber_optin

boolean

subscriber_optout

boolean

subscriber_help

boolean

sample_one

string

exampleSample Message

sample_two

string

exampleAdditional Sample Message

sample_three

string

exampleAdditional Sample Message

sample_four

string

exampleAdditional Sample Message

message_flow

string

examplestring

help_message

string

examplestring

affiliate_marketing

boolean

exampletrue

Example Request

{
   "identity_id": "BLQKOPK",
   "vertical": "TECHNOLOGY",
   "use_case": "ACCOUNT_NOTIFICATION",
   "sub_use_cases": [
      "2FA",
      "SECURITY_ALERT"
   ],
   "reseller_id": "string",
   "description": "User notifications",
   "embedded_link": false,
   "embedded_phone": false,
   "number_pool": false,
   "age_gated": true,
   "direct_lending": true,
   "subscriber_optin": false,
   "subscriber_optout": false,
   "subscriber_help": false,
   "sample_one": "Sample Message",
   "sample_two": "Additional Sample Message",
   "sample_three": "Additional Sample Message",
   "sample_four": "Additional Sample Message",
   "message_flow": "string",
   "help_message": "string",
   "affiliate_marketing": true
}

{
   "identity_id": "BLQKOPK",
   "vertical": "TECHNOLOGY",
   "use_case": "ACCOUNT_NOTIFICATION",
   "sub_use_cases": [
      "2FA",
      "SECURITY_ALERT"
   ],
   "reseller_id": "string",
   "description": "User notifications",
   "embedded_link": false,
   "embedded_phone": false,
   "number_pool": false,
   "age_gated": true,
   "direct_lending": true,
   "subscriber_optin": false,
   "subscriber_optout": false,
   "subscriber_help": false,
   "sample_one": "Sample Message",
   "sample_two": "Additional Sample Message",
   "sample_three": "Additional Sample Message",
   "sample_four": "Additional Sample Message",
   "message_flow": "string",
   "help_message": "string",
   "affiliate_marketing": true
}

Responses
Content Type
application/json

Return a single engagement

identity_id

string

exampleBLQKOPK

Identity ID associated with a number

vertical

string

exampleTECHNOLOGY

use_case

string

exampleACCOUNT_NOTIFICATION

sub_use_cases

array

reseller_id

string

examplestring

description

string

exampleUser notifications

embedded_link

boolean

embedded_phone

boolean

number_pool

boolean

age_gated

boolean

exampletrue

direct_lending

boolean

exampletrue

subscriber_optin

boolean

subscriber_optout

boolean

subscriber_help

boolean

sample_one

string

exampleSample Message

sample_two

string

exampleAdditional Sample Message

sample_three

string

exampleAdditional Sample Message

sample_four

string

exampleAdditional Sample Message

message_flow

string

examplestring

help_message

string

examplestring

affiliate_marketing

boolean

exampletrue

engagement_id

string

exampleC1DEB879

ID associated with a specific engagement

created_date

string

last_updated

string

_links

object

self

object

href

string

example/v1/messaging-engagement/engagements/57b3a89e-c9fa-4860-aec2-ad7f51539dab

numbers

object

href

string

Example Response

{
   "identity_id": "BLQKOPK",
   "vertical": "TECHNOLOGY",
   "use_case": "ACCOUNT_NOTIFICATION",
   "sub_use_cases": [
      "2FA",
      "SECURITY_ALERT"
   ],
   "reseller_id": "string",
   "description": "User notifications",
   "embedded_link": false,
   "embedded_phone": false,
   "number_pool": false,
   "age_gated": true,
   "direct_lending": true,
   "subscriber_optin": false,
   "subscriber_optout": false,
   "subscriber_help": false,
   "sample_one": "Sample Message",
   "sample_two": "Additional Sample Message",
   "sample_three": "Additional Sample Message",
   "sample_four": "Additional Sample Message",
   "message_flow": "string",
   "help_message": "string",
   "affiliate_marketing": true,
   "engagement_id": "C1DEB879",
   "created_date": "string",
   "last_updated": "string",
   "_links": {
      "self": {
         "href": "/v1/messaging-engagement/engagements/57b3a89e-c9fa-4860-aec2-ad7f51539dab"
      },
      "numbers": {
         "href": "string"
      }
   }
}

Retrieve a specific engagement

Get an engagement

gethttps://api.nexmo.com/v1/messaging-engagement/engagements/:engagement_id

Path Parameters

engagement_id

string

Required

exampleC1DEB879

ID associated with a specific engagement

Responses
Content Type
application/json

Return a single engagement

identity_id

string

exampleBLQKOPK

Identity ID associated with a number

vertical

string

exampleTECHNOLOGY

use_case

string

exampleACCOUNT_NOTIFICATION

sub_use_cases

array

reseller_id

string

examplestring

description

string

exampleUser notifications

embedded_link

boolean

embedded_phone

boolean

number_pool

boolean

age_gated

boolean

exampletrue

direct_lending

boolean

exampletrue

subscriber_optin

boolean

subscriber_optout

boolean

subscriber_help

boolean

sample_one

string

exampleSample Message

sample_two

string

exampleAdditional Sample Message

sample_three

string

exampleAdditional Sample Message

sample_four

string

exampleAdditional Sample Message

message_flow

string

examplestring

help_message

string

examplestring

affiliate_marketing

boolean

exampletrue

engagement_id

string

exampleC1DEB879

ID associated with a specific engagement

created_date

string

last_updated

string

_links

object

self

object

href

string

example/v1/messaging-engagement/engagements/57b3a89e-c9fa-4860-aec2-ad7f51539dab

numbers

object

href

string

Example Response

{
   "identity_id": "BLQKOPK",
   "vertical": "TECHNOLOGY",
   "use_case": "ACCOUNT_NOTIFICATION",
   "sub_use_cases": [
      "2FA",
      "SECURITY_ALERT"
   ],
   "reseller_id": "string",
   "description": "User notifications",
   "embedded_link": false,
   "embedded_phone": false,
   "number_pool": false,
   "age_gated": true,
   "direct_lending": true,
   "subscriber_optin": false,
   "subscriber_optout": false,
   "subscriber_help": false,
   "sample_one": "Sample Message",
   "sample_two": "Additional Sample Message",
   "sample_three": "Additional Sample Message",
   "sample_four": "Additional Sample Message",
   "message_flow": "string",
   "help_message": "string",
   "affiliate_marketing": true,
   "engagement_id": "C1DEB879",
   "created_date": "string",
   "last_updated": "string",
   "_links": {
      "self": {
         "href": "/v1/messaging-engagement/engagements/57b3a89e-c9fa-4860-aec2-ad7f51539dab"
      },
      "numbers": {
         "href": "string"
      }
   }
}

Partially update a specific engagement

Partial update of an engagement

patchhttps://api.nexmo.com/v1/messaging-engagement/engagements/:engagement_id

Path Parameters

engagement_id

string

Required

exampleC1DEB879

ID associated with a specific engagement

Request Body
Content Type
application/json

identity_id

string

exampleBLQKOPK

Identity ID associated with a number

vertical

string

exampleTECHNOLOGY

use_case

string

exampleACCOUNT_NOTIFICATION

sub_use_cases

array

reseller_id

string

examplestring

description

string

exampleUser notifications

embedded_link

boolean

embedded_phone

boolean

number_pool

boolean

age_gated

boolean

exampletrue

direct_lending

boolean

exampletrue

subscriber_optin

boolean

subscriber_optout

boolean

subscriber_help

boolean

sample_one

string

exampleSample Message

sample_two

string

exampleAdditional Sample Message

sample_three

string

exampleAdditional Sample Message

sample_four

string

exampleAdditional Sample Message

message_flow

string

examplestring

help_message

string

examplestring

affiliate_marketing

boolean

exampletrue

Example Request

{
   "identity_id": "BLQKOPK",
   "vertical": "TECHNOLOGY",
   "use_case": "ACCOUNT_NOTIFICATION",
   "sub_use_cases": [
      "2FA",
      "SECURITY_ALERT"
   ],
   "reseller_id": "string",
   "description": "User notifications",
   "embedded_link": false,
   "embedded_phone": false,
   "number_pool": false,
   "age_gated": true,
   "direct_lending": true,
   "subscriber_optin": false,
   "subscriber_optout": false,
   "subscriber_help": false,
   "sample_one": "Sample Message",
   "sample_two": "Additional Sample Message",
   "sample_three": "Additional Sample Message",
   "sample_four": "Additional Sample Message",
   "message_flow": "string",
   "help_message": "string",
   "affiliate_marketing": true
}

{
   "identity_id": "BLQKOPK",
   "vertical": "TECHNOLOGY",
   "use_case": "ACCOUNT_NOTIFICATION",
   "sub_use_cases": [
      "2FA",
      "SECURITY_ALERT"
   ],
   "reseller_id": "string",
   "description": "User notifications",
   "embedded_link": false,
   "embedded_phone": false,
   "number_pool": false,
   "age_gated": true,
   "direct_lending": true,
   "subscriber_optin": false,
   "subscriber_optout": false,
   "subscriber_help": false,
   "sample_one": "Sample Message",
   "sample_two": "Additional Sample Message",
   "sample_three": "Additional Sample Message",
   "sample_four": "Additional Sample Message",
   "message_flow": "string",
   "help_message": "string",
   "affiliate_marketing": true
}

Responses
Content Type
application/json

Return a single engagement

identity_id

string

exampleBLQKOPK

Identity ID associated with a number

vertical

string

exampleTECHNOLOGY

use_case

string

exampleACCOUNT_NOTIFICATION

sub_use_cases

array

reseller_id

string

examplestring

description

string

exampleUser notifications

embedded_link

boolean

embedded_phone

boolean

number_pool

boolean

age_gated

boolean

exampletrue

direct_lending

boolean

exampletrue

subscriber_optin

boolean

subscriber_optout

boolean

subscriber_help

boolean

sample_one

string

exampleSample Message

sample_two

string

exampleAdditional Sample Message

sample_three

string

exampleAdditional Sample Message

sample_four

string

exampleAdditional Sample Message

message_flow

string

examplestring

help_message

string

examplestring

affiliate_marketing

boolean

exampletrue

engagement_id

string

exampleC1DEB879

ID associated with a specific engagement

created_date

string

last_updated

string

_links

object

self

object

href

string

example/v1/messaging-engagement/engagements/57b3a89e-c9fa-4860-aec2-ad7f51539dab

numbers

object

href

string

Example Response

{
   "identity_id": "BLQKOPK",
   "vertical": "TECHNOLOGY",
   "use_case": "ACCOUNT_NOTIFICATION",
   "sub_use_cases": [
      "2FA",
      "SECURITY_ALERT"
   ],
   "reseller_id": "string",
   "description": "User notifications",
   "embedded_link": false,
   "embedded_phone": false,
   "number_pool": false,
   "age_gated": true,
   "direct_lending": true,
   "subscriber_optin": false,
   "subscriber_optout": false,
   "subscriber_help": false,
   "sample_one": "Sample Message",
   "sample_two": "Additional Sample Message",
   "sample_three": "Additional Sample Message",
   "sample_four": "Additional Sample Message",
   "message_flow": "string",
   "help_message": "string",
   "affiliate_marketing": true,
   "engagement_id": "C1DEB879",
   "created_date": "string",
   "last_updated": "string",
   "_links": {
      "self": {
         "href": "/v1/messaging-engagement/engagements/57b3a89e-c9fa-4860-aec2-ad7f51539dab"
      },
      "numbers": {
         "href": "string"
      }
   }
}

Update a specific engagement

Update an engagement

puthttps://api.nexmo.com/v1/messaging-engagement/engagements/:engagement_id

Path Parameters

engagement_id

string

Required

exampleC1DEB879

ID associated with a specific engagement

Request Body
Content Type
application/json

identity_id

string

exampleBLQKOPK

Identity ID associated with a number

vertical

string

exampleTECHNOLOGY

use_case

string

exampleACCOUNT_NOTIFICATION

sub_use_cases

array

reseller_id

string

examplestring

description

string

exampleUser notifications

embedded_link

boolean

embedded_phone

boolean

number_pool

boolean

age_gated

boolean

exampletrue

direct_lending

boolean

exampletrue

subscriber_optin

boolean

subscriber_optout

boolean

subscriber_help

boolean

sample_one

string

exampleSample Message

sample_two

string

exampleAdditional Sample Message

sample_three

string

exampleAdditional Sample Message

sample_four

string

exampleAdditional Sample Message

message_flow

string

examplestring

help_message

string

examplestring

affiliate_marketing

boolean

exampletrue

Example Request

{
   "identity_id": "BLQKOPK",
   "vertical": "TECHNOLOGY",
   "use_case": "ACCOUNT_NOTIFICATION",
   "sub_use_cases": [
      "2FA",
      "SECURITY_ALERT"
   ],
   "reseller_id": "string",
   "description": "User notifications",
   "embedded_link": false,
   "embedded_phone": false,
   "number_pool": false,
   "age_gated": true,
   "direct_lending": true,
   "subscriber_optin": false,
   "subscriber_optout": false,
   "subscriber_help": false,
   "sample_one": "Sample Message",
   "sample_two": "Additional Sample Message",
   "sample_three": "Additional Sample Message",
   "sample_four": "Additional Sample Message",
   "message_flow": "string",
   "help_message": "string",
   "affiliate_marketing": true
}

{
   "identity_id": "BLQKOPK",
   "vertical": "TECHNOLOGY",
   "use_case": "ACCOUNT_NOTIFICATION",
   "sub_use_cases": [
      "2FA",
      "SECURITY_ALERT"
   ],
   "reseller_id": "string",
   "description": "User notifications",
   "embedded_link": false,
   "embedded_phone": false,
   "number_pool": false,
   "age_gated": true,
   "direct_lending": true,
   "subscriber_optin": false,
   "subscriber_optout": false,
   "subscriber_help": false,
   "sample_one": "Sample Message",
   "sample_two": "Additional Sample Message",
   "sample_three": "Additional Sample Message",
   "sample_four": "Additional Sample Message",
   "message_flow": "string",
   "help_message": "string",
   "affiliate_marketing": true
}

Responses
Content Type
application/json

Return a single engagement

identity_id

string

exampleBLQKOPK

Identity ID associated with a number

vertical

string

exampleTECHNOLOGY

use_case

string

exampleACCOUNT_NOTIFICATION

sub_use_cases

array

reseller_id

string

examplestring

description

string

exampleUser notifications

embedded_link

boolean

embedded_phone

boolean

number_pool

boolean

age_gated

boolean

exampletrue

direct_lending

boolean

exampletrue

subscriber_optin

boolean

subscriber_optout

boolean

subscriber_help

boolean

sample_one

string

exampleSample Message

sample_two

string

exampleAdditional Sample Message

sample_three

string

exampleAdditional Sample Message

sample_four

string

exampleAdditional Sample Message

message_flow

string

examplestring

help_message

string

examplestring

affiliate_marketing

boolean

exampletrue

engagement_id

string

exampleC1DEB879

ID associated with a specific engagement

created_date

string

last_updated

string

_links

object

self

object

href

string

example/v1/messaging-engagement/engagements/57b3a89e-c9fa-4860-aec2-ad7f51539dab

numbers

object

href

string

Example Response

{
   "identity_id": "BLQKOPK",
   "vertical": "TECHNOLOGY",
   "use_case": "ACCOUNT_NOTIFICATION",
   "sub_use_cases": [
      "2FA",
      "SECURITY_ALERT"
   ],
   "reseller_id": "string",
   "description": "User notifications",
   "embedded_link": false,
   "embedded_phone": false,
   "number_pool": false,
   "age_gated": true,
   "direct_lending": true,
   "subscriber_optin": false,
   "subscriber_optout": false,
   "subscriber_help": false,
   "sample_one": "Sample Message",
   "sample_two": "Additional Sample Message",
   "sample_three": "Additional Sample Message",
   "sample_four": "Additional Sample Message",
   "message_flow": "string",
   "help_message": "string",
   "affiliate_marketing": true,
   "engagement_id": "C1DEB879",
   "created_date": "string",
   "last_updated": "string",
   "_links": {
      "self": {
         "href": "/v1/messaging-engagement/engagements/57b3a89e-c9fa-4860-aec2-ad7f51539dab"
      },
      "numbers": {
         "href": "string"
      }
   }
}

Stop a specific engagement on an identity

Stop an engagement

deletehttps://api.nexmo.com/v1/messaging-engagement/engagements/:engagement_id

Path Parameters

engagement_id

string

Required

exampleC1DEB879

ID associated with a specific engagement

Responses

No content

Numbers

APIs relating to working with Numbers in Engagements

Available Operations

Retrieve Numbers associated with an engagement

Get numbers in engagement

gethttps://api.nexmo.com/v1/messaging-engagement/engagements/:engagement_id/numbers

Path Parameters

engagement_id

string

Required

exampleC1DEB879

ID associated with a specific engagement

Responses
Content Type
application/json

List of numbers that are associated with an engagement

page_size

integer

example10

Items per page

page

integer

Min1

example2

Page Offset

total_pages

integer

Min1

example100

Number of pages in the entire result set

total_items

integer

example100

Number of items in the entire result set

_embedded

object

numbers

array

_links

object

engagement

object

href

string

example

{
  "value": "https://api.nexmo.com/v1/messaging-engagement/engagements/C1DEB879/"
}

Example Response

{
   "page_size": 10,
   "page": 2,
   "total_pages": 100,
   "total_items": 100,
   "_embedded": {
      "numbers": [
         "15556660001",
         "15556660002"
      ],
      "_links": {
         "engagement": {
            "href": {
               "value": "https://api.nexmo.com/v1/messaging-engagement/engagements/C1DEB879/"
            }
         }
      }
   }
}

Add numbers to an engagement

Adds a series of numbers from an engagement. This endpoint supports partial successes. If a request is partially successful, the response code will be 207 and details can be found in the response body.

If all items succeed, you will receive a 200. If all items fail, you will receive a 400.

posthttps://api.nexmo.com/v1/messaging-engagement/engagements/:engagement_id/numbers

Path Parameters

engagement_id

string

Required

exampleC1DEB879

ID associated with a specific engagement

Request Body
Content Type
application/json

numbers

array

Required

Example Request

{
   "numbers": [
      "15556660001",
      "15556660002"
   ]
}

{
   "numbers": [
      "15556660001",
      "15556660002"
   ]
}

Responses
Content Type
application/json

Successful bulk operation

numbers

array

_links

object

engagement

object

href

string

example

{
  "value": "https://api.nexmo.com/v1/messaging-engagement/engagements/C1DEB879/"
}

Example Response

{
   "numbers": [
      "15556660001",
      "15556660002"
   ],
   "_links": {
      "engagement": {
         "href": {
            "value": "https://api.nexmo.com/v1/messaging-engagement/engagements/C1DEB879/"
         }
      }
   }
}

Remove a series of number from an engagement

Remove a series of numbers from an engagement. This endpoint supports partial successes. If a request is partially successful, the response code will be 207 and details can be found in the response body.

If all items succeed, you will receive a 200. If all items fail, you will receive a 400.

posthttps://api.nexmo.com/v1/messaging-engagement/engagements/:engagement_id/numbers/delete

Path Parameters

engagement_id

string

Required

exampleC1DEB879

ID associated with a specific engagement

Request Body
Content Type
application/json

numbers

array

Required

Example Request

{
   "numbers": [
      "15556660001",
      "15556660002"
   ]
}

{
   "numbers": [
      "15556660001",
      "15556660002"
   ]
}

Responses
Content Type
application/json

Successful bulk operation

numbers

array

_links

object

engagement

object

href

string

example

{
  "value": "https://api.nexmo.com/v1/messaging-engagement/engagements/C1DEB879/"
}

Example Response

{
   "numbers": [
      "15556660001",
      "15556660002"
   ],
   "_links": {
      "engagement": {
         "href": {
            "value": "https://api.nexmo.com/v1/messaging-engagement/engagements/C1DEB879/"
         }
      }
   }
}

Identity Verification and Message Engagement Registration

Identities

Available Operations

Retrieve all of the identities associated with your account.

Responses Content Typeapplication/json

Example Response

Create a new identity for your account

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Retrieve a specific identity

Path Parameters

Responses Content Typeapplication/json

Example Response

Partially update a specific identity

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Update a specific identity

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Remove a specific identity from your account

Path Parameters

Responses

Engagements

Available Operations

Retrieve all of the engagements

Responses Content Typeapplication/json

Example Response

Add a new engagement to an identity

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Retrieve a specific engagement

Path Parameters

Responses Content Typeapplication/json

Example Response

Partially update a specific engagement

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Update a specific engagement

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Stop a specific engagement on an identity

Path Parameters

Responses

Numbers

Available Operations

Retrieve Numbers associated with an engagement

Path Parameters

Responses Content Typeapplication/json

Example Response

Add numbers to an engagement

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Remove a series of number from an engagement

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json