GET Retrieve a Consumer Profile

GET /consumer/v2/profiles/{profileId}

Development Guide

The Retrieve a Consumer Profile API returns a consumer's profile by profileId. Optionally, it can respond with all the receivers for the consumer and the last transaction sent to each receiver.



1. Prepare headers & authentication:

The application must call the Retrieve Consumer Profile endpoint with a GET HTTP method, providing the OAuth access_token in the header and all other required header and query parameters.


NOTE: MoneyGram uses the OAuth 2.0 framework. The application must use their OAuth client credentials to generate an accessToken by calling the Get access token endpoint. The token is valid for 1 hour and must be passed as a header value in all subsequent API HTTP calls. Learn More


🚀

Launch Example Code




2. Provide profileId as a path parameter:

The application must provide the profileId as a path parameter.


🚀

Launch Example Code




3. Choose to returnReceivers for the Consumer (optional):

Include the returnReceivers query parameter in the Retrieve Consumer Profiles API to optionally return all the receivers associated with the consumer and the last transaction sent to each receiver.


🚀

Launch Example Code




4. Make the request and handle the response:

The application will call the 'Retrieve Consumer Profiles' endpoint with a GET HTTP method. The application must build to handle the following response scenarios.


  • Success | Parse the Response | 200 OK HTTP Status
    When the Retrieve Consumer Profiles endpoint responds with a 200 HTTP Status, the response will return the that was updated.

  • Success | Consumer Profile lookup has no content | 204 No Content HTTP Status
    When the 'Retrieve Consumer Profiles' endpoint responds with 204 HTTP Status. The 'Retrieve Consumer Profiles' endpoint API will return a message of "204 No Content" message.

  • Failed | Handle the Error | 400 Bad Request HTTP Status
    When the Retrieve Consumer Profiles endpoint responds with 400 HTTP Status, specific error code/s will be returned with an array of offending fields. The application will need to resolve these errors and resubmit the update request


🚀

Launch Example Code

.

.





Code Examples

const axios = require('axios');
const { v4: uuidv4 } = require('uuid');

const retrieveConsumerProfile = async () => {

    // Step 1: Read configuration values with upmost security
    const token = "your_access_token_from_oauth_response"
    // For production - api.moneygram.com & For test - sandboxapi.moneygram.com
    const host = "sandboxapi.moneygram.com";
    const url = 'https://' + host + '/consumer/v2/profiles';

    // Step 2: Create the GET request headers & params
    const headers = {
        'Content-Type': 'application/json',
        'X-MG-ClientRequestId': uuidv4(), // New UUID for each request tracing
        'Authorization': 'Bearer ' + token,
    };

    const profileId = "consumer_profile_id";
    const params = {
        'agentPartnerId': 'your_partner_id',
        'userLanguage': 'en-US',
        'returnReceivers': true
    }

    try {
        // Step 3: Send the request and obtain the response
        axios.get(url + '/' + profileId, { params, headers })
            .then(function (response) {
                // Step 4: Parse the success response and process further
                console.log(JSON.stringify(response.data, null, 2))
            })
            .catch(function (error) {
                // Step 5: Parse the error response and handle the errors
                if (error.response) {
                    console.log('Response status:', error.response.status);
                    console.log('Response body:', error.response.data);
                } else {
                    // TODO: handle generic errors
                    console.error('Error:', error.message);
                }
            });
    } catch (error) {
        // TODO: handle exception
        console.error('Error:', error.message);
    }
};

retrieveConsumerProfile();

import requests
import uuid
import json

def retrieve_consumer_profile():

    # Step 1: Read configuration values with upmost security
    token = "your_access_token_from_oauth_response"
    # For production - api.moneygram.com & For test - sandboxapi.moneygram.com
    host = "sandboxapi.moneygram.com"
    url = 'https://' + host + '/consumer/v2/profiles'

    # Step 2: Create the GET request headers & params
    headers = {
        'Content-Type': 'application/json',
        'X-MG-ClientRequestId': str(uuid.uuid4()), # New UUID for each request tracing
        'Authorization': 'Bearer ' + token,
    }

    profileId = "consumer_profile_id"
    params = {
        'agentPartnerId': 'your_partner_id',    
        'userLanguage': 'en-US',
        'returnReceivers': 'true'
    }

    try:
        # Step 3: Send the request and obtain the response
        response = requests.get(url + '/' + profileId, params=params, headers=headers)

        # Step 4: Parse the success response and process further
        if response.status_code == 200:
            parsed_response = json.dumps(json.loads(response.text), indent=2)
            print(parsed_response)
        else:
            # Print the error message if request fails
            # TODO: handle exception
            print("Request failed with status code:", response.status_code)
            print(json.loads(json.dumps(response.text, indent=4)))

    except requests.exceptions.RequestException as e:
        # Print any error that occurred during the request
        # TODO: handle exception
        print("An error occurred:", e)

retrieve_consumer_profile()
package consumer;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.UUID;

public class RetrieveConsumerProfile {

    public static void main(String[] args) {
        // Step 1: Read configuration values with upmost security
        String token = "your_access_token_from_oauth_response";

        // For production - api.moneygram.com & For test - sandboxapi.moneygram.com
        String host = "sandboxapi.moneygram.com";

        // Step 2: Create the GET request headers & params
        // Mandatory Query params
        String agentPartnerId = "your_partner_id";
        String userLanguage = "en-US";
        String returnReceivers = true


        // Optional Query params
        String targetAudience = "AGENT_FACING";

        // Mandatory Path params
        String profileId = "consumer_profile_id";

        String uri = "https://" + host + "/consumer/v2/profiles/" + profileId + "?"
                + "agentPartnerId=" + agentPartnerId
                + "&userLanguage=" + userLanguage
                + "&returnReceivers=" + returnReceivers
                + (targetAudience.isBlank() ? "" : "&targetAudience=" + targetAudience)

        HttpClient httpClient = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(uri))
                .GET()
                .setHeader("Authorization", "Bearer " + token)
                .setHeader("X-MG-ClientRequestId", String.valueOf(UUID.randomUUID()))
                .build();

        try {
            // Step 3: Send the request and obtain the response
            HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            // Retrieve the status code and body from the response
            int statusCode = response.statusCode();

            // Step 4: Parse the success response and process further
            if (statusCode == 200) {
                String responseBody = response.body();
                System.out.println(responseBody);
            } else {
                // Step 5: Parse the error response and handle the errors
                String responseBody = response.body();
                System.out.println(responseBody);
            }
        } catch (Exception e) {
            e.printStackTrace();
            // TODO: handle exception
        }

    }
}




API Structure


Header Parameters

FieldTypeRequired/OptionalDescription
X-MG-ClientRequestIdStringOptionalClient Request ID that can be passed by the client application. Client request Id must be unique within a single session for unique requests. This attribute can be used for ensuring idempotent request processing for some APIs. MoneyGram recommends using a UUID for the value of this field.
X-MG-ConsumerIPAddressStringOptionalIP Address of the system initiating the session


Path Parameters

FieldTypeRequired
/Optional
Description
profileIdStringRequiredConsumer's unique identifier


Query Parameters

FieldTypeRequired/
Optional
Description
targetAudienceStringOptionalTailors MoneyGram’s error messages and field metadata to an in-store, digital or crypto customer. (Enumerated value)

NOTE: For a full list of accepted target audience values. See the TARGET_AUDIENCE enumeration from the Reference Data Enumerations endpoint
agentPartnerIdStringRequiredUnique agent or partner identifier.
userLanguageStringRequiredLanguage used by the user/operator.
returnReceiversBooleanOptionalFlag to indicate that all the receivers for the consumer should be returned and the last transaction sent to each receiver.


Response Fields

FieldTypeRequired
/Optional
Description
consumer.name.firstNameString
Min length: 1
Max length: 20
RequiredFirst Name
consumer.name.middleNameString
Min length: 1
Max length: 20
OptionalMiddle Name (if applicable)
consumer.name.lastNameString
Min length: 1
Max length: 30
RequiredLast Name
consumer.name.secondLastNameString
Min length: 1
Max length: 30
OptionalSecond Last Name
consumer.address.line1String
Min length: 5
Max length: 30
RequiredResidence address line 1
consumer.address.line2String
Min length: 1
Max length: 80
OptionalResidence address line 2 (if applicable)
consumer.address.line3String
Min length: 1
Max length: 80
OptionalResidence address line 3 (if applicable)
consumer.address.cityString
Min length: 1
Max length: 20
RequiredCity of residence
consumer.address.countrySubdivisionCodeString
Length: 6
OptionalState/province of residence

NOTE: For a full list of accepted countries and supported destination country subdivision codes see Reference Data API Module: Retrieve Countries ISO3 endpoint
consumer.address.countryCodeString
Length: 3
RequiredCountry of residence (ISO Alpha-3 Code)

NOTE: For a full list of accepted countries and supported destination country subdivision codes see Reference Data API Module: Retrieve Countries ISO3 endpoint
consumer.address.postalCodeString
Min length: 2
Max length: 6
OptionalPostal/Zip code of residence
consumer.phone.numberString
Min length: 5
Max length: 14
OptionalPhone number
consumer.phone.countryDialCodeString
Min length: 1
Max length: 3
OptionalCountry dial code

NOTE: For country calling code see Reference Data API Module /countries endpoint phoneDialCodes
consumer.email.emailString
Min length: 1
Max length: 255
OptionalEmail Address
consumer.rewardsNumberStringOptionalUnique code to apply Loyalty accrual/redemption (MoneyGram Plus Number)
consumer.notificationPreferences.typeStringOptionalConsumer notification preference types
consumer.notificationPreferences.channelDelivery method of notification

NOTE: For notification preference channels see: Reference Data API Module CNSMR_OPTIN
consumer.notificationPreferences.optInBooleanOptionalFlag to declare consumer opts-in to notification type and method
consumer.notificationLanguagePreferenceString
Max length: 6
OptionalLanguage (ISO alpha-3 code)
consumer.personalDetails.genderCodeStringOptionalGender (Enumerated Value)
consumer.personalDetails.dateOfBirthString
Length: 10
RequiredDate of birth (YYYY-MM-DD)
consumer.personalDetails.birthCityString
Min length: 0
Max length: 20
OptionalCity of birth
consumer.personalDetails.birthCountryCodeString
Max Length: 3
RequiredCountry of birth (ISO alpha-3 code)

NOTE: For a full list of accepted birth.CountryCodes see ‘Reference Data API Module’ and the Retrieve Countries ISO3 endpoint: ]
consumer.personalDetails.citizenshipCountryCodeString
Max Length: 3
OptionalCountry of birth. (ISO alpha-3 code)
consumer.personalDetails.occupationCodeStringOptionalOccupation/Employment (Enumerated Value)

NOTE: For a full list of accepted occupation codes see Reference Data Enumerations endpoint
consumer.personalDetails.politicalExposedPersonBooleanOptionalFlag to declare a Politically Exposed Person (PEP)
consumer.personalDetails.nationalityCountryCodeString
Min Length: 3
Max Length: 3
OptionalCountry of citizenship (ISO alpha-3 code)
consumer.additionalFamilyNames.typeStringOptionalType of family name (Enumerated Values)

- FATHERS_S_NAME
- MOTHER_S_NAME
- SIBLING_S_NAME
- NAME_AT_BIRTH
- MOTHERS_MAIDEN_NAME
- GRANDFATHER_S_NAME
consumer.additionalFamilyNames.firstNameString
Min length: 0
Max length: 20
OptionalFirst Name
consumer.additionalFamilyNames.middleNameString
Min length: 0
Max length: 20
OptionalMiddle Name (if applicable)
consumer.additionalFamilyNames.lastNameString
Min length: 0
Max length: 20
OptionalLast Name
consumer.additionalFamilyNames.secondLastNameString
Min length: 0
Max length: 30
OptionalSecond Last Name
receivers.name.firstNameString
Min length: 1
Max length: 20
RequiredFirst Name
receivers.name.middleNameString
Min length: 0
Max length: 20
OptionalMiddle Name (if applicable)
receivers.name.lastNameString
Min length: 1
Max length: 20
RequiredLast Name
receivers.name.secondLastNameString
Min length: 0
Max length: 20
OptionalSecond Last Name
receivers.receiver.address.line1String
Min length: 5
Max length: 30
RequiredResidence address line 1
receivers.address.line2String
Min length: 0
Max length: 30
OptionalResidence address line 2 (if applicable)
receivers.address.line3String
Min length: 0
Max length: 30
OptionalResidence address line 3 (if applicable)
receivers.address.cityString
Min length: 1
Max length: 20
RequiredCity of residence
receivers.address.countrySubdivisionCodeString
Max length: 6
OptionalState/province of residence
receivers.address.countryCodeString
Max length: 3
RequiredCountry of residence (ISO Alpha-3 Code)
receivers.address.postalCodeString
Min length: 2
Max length: 6
OptionalPostal code/ZIP of residence
receivers.phone.numberString
Min length: 5
Max length: 14
OptionalPhone number
receivers.phone.countryDialCodeString
Min length: 1
Max length: 3
OptionalCountry dial code
receivers.destinationCountryCodeString
Max Length: 3
RequiredTransaction Destination Country (ISO alpha-3 code)

NOTE: For a full list of accepted destination Countries and supported destinationCountrySubdivisionCode see Reference Data API Module: Retrieve Countries ISO3 endpoint
receivers.destinationCountrySubdivisionCodeString
Max length: 6
Conditionally RequiredDestination state/province is conditionally required when transacting to the United States or Canada.

NOTE: For a full list of accepted destination Countries and supported destinationCountrySubdivisionCode see Reference Data API Module: Retrieve Countries ISO3 Endpoint
receivers.serviceOptionCodeString
Max length: 21
RequiredUnique category code to identify the transaction method

NOTE: For a full list of accepted service option codes per destination country see the Reference Data API Module: service-options endpoint
receivers.serviceOptionNameStringRequiredConsumer facing name to identify the transaction method
receivers.serviceOptionRoutingCodeString
Max length: 21
OptionalUnique code to identify the individual transaction method

NOTE: For a full list of accepted service option codes per destination country see the Reference Data API Module: service-options endpoint
receivers.serviceOptionRoutingNameStringOptionalUnique name to identify the individual transaction method
receivers.sendAmount.valueString
Min length: 0
Max length: 14
Max Decimal Value: 3
RequiredTransaction amount and currency excluding fees and exchange rate.

NOTE: For Crypto partners this is the fiat currency for the BUY/Sell or Ramp-on/Ramp-off

For a full list of transaction currency codes see the API Reference Data Module: currencies endpoint
receivers.sendAmount.currencyCodeString
Max length: 3
RequiredThe sendAmount.value currency code for a transactBySendAmountRequest (ISO alpha-3 code)
receivers.receiveCurrencyCodeString
Max length: 3
RequiredReceive currency code for the destination country transactBySendAmount Request (ISO alpha-3 code)
receivers.targetAccountProfileIdStringOptionalUnique Identifier for Target Account Resource
receivers.targetAccountDisplayNumberStringOptionalThe last four digits of the target account number