Managing Consumers

Example Queries

The following example queries make use of GraphQL's variables feature for injecting dynamic data into queries. In the GraphiQL UI, for example, you can open the "Variables" pane at the bottom left of the screen to insert variables into your query.

Create a Consumer

Consumers (a.k.a. "borrowers") are the basis of most GraphQL operations. If you're using Nexus, a consumer will be created automatically when someone launches Nexus. (Be sure to record their UUID from the Nexus response to query their data later on.) But if you've already created a consumer, you can specify their UUID in the consumer: option when launching Nexus.

You can also update a consumer's financial details and information about their spouse (which are required for some Nexus workflows like Nexus.studentLoanEnroll).

mutation($consumer: ConsumerInput!) {
  createConsumer(consumer: $consumer) {
    uuid
    firstName
    lastName
    email
    dateOfBirth
    address {
      city
      state
      street1
      street2
      zipcode
    }
    financialDetails {
      agi
      filingStatus
      familySize
      maritalStatus
    }
    spouse {
      agi
      dateOfBirth
      federalLoanBalance
      firstName
      lastName
    }
  }
}

The variables to create a consumer should include the following example PII:

{
  "consumer": {
    "address": {
      "city": "Indianapolis",
      "state": "IN",
      "street1": "500 Speedway Street",
      "street2": "Apt. 5B",
      "zipcode": "46000"
    },
    "dateOfBirth": "1945-05-01",
    "email": "[email protected]",
    "externalId": "abc123",
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "999-999-9999",
    "ssn": "123456789",
    "agi": 55000,
    "filingStatus": "MARRIED_FILING_JOINTLY",
    "familySize": 4,
    "maritalStatus": "MARRIED",
    "spouse": {
      "agi": 65000,
      "dateOfBirth": "1982-05-01",
      "federalLoanBalance": "42654.12",
      "firstName": "John",
      "lastName": "Smith",
      "ssn": "234567890"
    }
  }
}

List Consumers

Once you have created a consumer, you may want to list them. To do so, you'll query consumers. We use cursor based pagination and the query will take an optional afterCursor arg. When the arg is not passed, results for the first page will be returned with an endCursor key under the pageInfo section. The endCursor value can then be passed as the value for the afterCursor arg in order to receive the next page of results if there is one. The query also accepts a limit arg. The default limit when the arg is not passed is 50 and the max is 100.

In your response, you will also receive additional information that includes the totalCount of consumers and a key of hasNextPage which indicates if there is a page after this one available.

query {
  consumers(limit: 1, afterCursor: "g3MjUwYUdFRWR3cGZYM04wY25WamRTFwYm5WMFpXRWZkd1JvYjNWeVlSSjNDW987687hjkbkjhljhLJHBLJHFJwYldWZmVtOXVaVzBBQUFBSFJYUmpMMVZVUTNjSmVtOXVaVW1abk5sZEdFQQ=="){
    nodes{
      uuid
      createdAt
      firstName
      lastName
      email
    }
    pageInfo{
      endCursor
      hasNextPage
    }
    totalCount
  }
}

Example Results

{
  "data": {
    "consumers": {
      "nodes": [
        {
          "createdAt": "2023-04-28T18:34:16.458863Z",
          "email": "[email protected]",
          "firstName": "Kamron",
          "lastName": "Kuphal",
          "uuid": "c7876GHb-4c99-488c-b42c-2bGH709dd1c"
        }
      ],
      "pageInfo": {
        "endCursor": "g3QAAAABQUNkd0pwWkdFQ2Gc1pXNWtZWEl1U1dfgdgHKHJjnkjkljblkj8998hjvljJLHVBLJNVJHjhbjkhGKJHBGR3VnRiMjUdBQUItZDNCbTFwYm5WMFpXRWlWVEdFQQ==",
        "hasNextPage": true
      },
      "totalCount": 2066
    }
  }
}

Filter Consumer Results

Optionally you can filter the results from your list of consumers by adding constraints to your query. Each of these fields support wildcards so will return any consumer containing part of any of these fields:

email
firstName
lastName

query {
  consumers(email: "jones", firstName: "Indi", lastName: "Jones") {
    nodes{
      uuid
      createdAt
      firstName
      lastName
      email
    }
    pageInfo{
      endCursor
      hasNextPage
    }
    totalCount
  }
}

Example Results

{
  "data": {
    "consumers": {
      "nodes": [
        {
          "createdAt": "2023-04-28T18:34:16.458863Z",
          "email": "[email protected]",
          "firstName": "Indiana",
          "lastName": "Jones",
          "uuid": "c7876GHb-4c99-488c-b42c-2bGH709dd1c"
        },
        {
          "createdAt": "2023-04-28T18:34:16.458863Z",
          "email": "[email protected]",
          "firstName": "Indiano",
          "lastName": "Jonesy",
          "uuid": "c7876GHb-ffff-488c-8765-2bGH709dd1c"
        }
      ],
      "pageInfo": {
        "endCursor": "g3QAAAABQUNkd0pwWkdFQ2Gc1pXNWtZWEl1U1dfgdgHKHJjnkjkljblkj8998hjvljJLHVBLJNVJHjhbjkhGKJHBGR3VnRiMjUdBQUItZDNCbTFwYm5WMFpXRWlWVEdFQQ==",
        "hasNextPage": false
      },
      "totalCount": 2
    }
  }
}

Types 🚧

Explore our complete GraphQL schema in the GraphiQL UI available at https://payitoff-sandbox.io/api/graphql-playground (just click the "< Docs" tab at right).